中文版

Partner API — Enquiries and Offers

Authorised partners can read and respond to tenant viewing requests, exchange thread messages, and read offers through the Partner API, limited to properties they created. Consent-only permissions, scoped SQL readers, existing landlord workflows, and audit attribution preserve privacy and access boundaries without granting offer negotiation or acceptance authority.

  • Predecessor Partner API foundation (P1), property lifecycle (P2), and P3 shared landlord scope and consent presentation
  • Status Approved

View source markdown ↗ generated by openai-codex/gpt-6.1-sol · diagrams mermaid

Let authorised partners handle tenant enquiries between listing management and tenancy operations: read viewing requests, respond to viewing times, exchange thread messages, and read offers. Access is limited to properties created by the calling partner; offer negotiation and acceptance remain outside the API.

Decisions at a glance

  • AudienceWhite-label partners, then portals and CRMs
  • Surface/api/partner/v1
  • AuthorityViewing actions and messages; offers read-only
  • BoundaryExplicit consent and partner-created properties
DecisionLocked-in choice
Operation scopeMirror landlord v1 exactly: viewing reads/actions, thread reads/posts, offer reads only.
Property visibilityThe immutable origin_partner_id must equal the caller. No all-properties opt-in.
ConsentBoth enquiries:read and enquiries:write require landlord approval.
ImplementationReuse V1EnquiryHandler and existing workflows; pass explicit port.LandlordScope and filter in SQL.
IdentityAct as the landlord; keep sent_via: "api" and record the real partner in audit.
RetriesReuse message-post idempotency with landlord-scoped partner keys. No new viewing-action idempotency contract.
LifecycleArchived history remains readable. Existing rental workflow rules govern actions and messages.

Intent and success

Partners start with first-party white-label channels and later include external portals and CRMs. They need to serve authorised landlords through the gap between listing management and P3 tenancy operations, without authority to negotiate or accept offers.

Success means viewing-request list/detail, confirm/counter/decline, thread read/send, and offer list/detail on the partner surface. Tenant disclosure and business behaviour match the existing landlord v1 API.

Programme
The enquiries-and-offers item explicitly deferred by P1; no change to P1–P3 acceptance criteria.
Dependencies
P1 Partner API foundation, P2 property lifecycle, and P3 shared landlord scope and consent presentation.
Ownership
backend/go, backend/bun, frontend/solidstart/apps/rental, and frontend/solidstart/apps/panel.
Concurrent work
The source records P2 frontend and P3 backend/frontend implementation in other sessions. Integrate with their delivered interfaces; do not duplicate that work.

Architecture and alternatives

Shared handlers, explicit readers

Reuse V1EnquiryHandler and migrate enquiry readers to P3’s port.LandlordScope.

One enquiry workflow preserves v1 response shaping and business behaviour. SQL visibility keeps detail access, page contents, and totals consistent with P3.

Separate partner handlers/readers reduce changes to v1 callers but duplicate shaping and visibility logic. Per-resource checks around unchanged readers split authorisation between checks and queries and still need SQL changes for pagination.

The path landlord is the acting user; the authenticated partner remains the audit actor. Internal visibility reads do not add an endpoint read-permission requirement to a write action
The path landlord is the acting user; the authenticated partner remains the audit actor. Internal visibility reads do not add an endpoint read-permission requirement to a write action.

Existing foundation, not implementation claims

Observed code boundaries and source designs
  • adapter/inbound/http/v1_routes.go mounts the nine enquiry routes using enquiries:read/enquiries:write; deeper offer-action paths deliberately return 404 before authentication.
  • adapter/inbound/http/v1_enquiry_handler.go shapes viewing requests, messages, and offers without user IDs or structured tenant contact details. The action helper reads the visible request before the workflow and again afterwards.
  • Message posting checks visibility before sending; replay resolves through GetOwnerMessage. PeekMessages reads never mark messages read.
  • ViewingRequestUseCase: ListOwnerPage, GetOwnerView, PeekMessages, GetOwnerMessage. OfferUseCase: ListLandlordPage, GetLandlordView. These currently take (ownerID/landlordID, isTest), not a partner-aware scope.
  • adapter/outbound/persistence/postgresql/message_repository.go currently stamps sent_via = 'api' only for actor_type == 'api_key'.
  • P1 combines key ceiling, landlord grant, and live landlord scope; partner_scope.go contains the landlord-scoped idempotency-key helper.
  • P3 introduces port.LandlordScope{UserID, IsTest, PartnerID}, consent-only enforcement, shared translated scope presentation, and a consent-only panel group. Reuse those delivered seams.

Source designs in docs/superpowers/specs/: 2026-10-03-partner-api-p1-design.md, 2026-10-03-landlord-api-enquiries-design.md, and 2026-10-07-partner-api-p3-design.md.

API contract

Base: /api/partner/v1/landlords/:landlord_id. The following relative paths preserve landlord v1 bodies and responses.

MethodRelative pathRequired scope
GET/viewing-requestsenquiries:read
GET/viewing-requests/:idenquiries:read
POST/viewing-requests/:id/confirmenquiries:write
POST/viewing-requests/:id/counterenquiries:write
POST/viewing-requests/:id/declineenquiries:write
GET/viewing-requests/:id/messagesenquiries:read
POST/viewing-requests/:id/messagesenquiries:write
GET/offersenquiries:read
GET/offers/:idenquiries:read
Viewing list filters
status, listing_id.
Offer list filters
status, viewing_request_id.
Write body fields
Confirm: confirmed_time; counter: proposed_times; decline: reason; message: body.
Preserved contract
Existing body validation, response fields, timestamps, sorting, and pagination envelope.

Authorisation and reader boundaries

Three visibility predicates

  1. Landlord match

    Resolve the existing listing/property relationship; the landlord or owner must match scope.UserID.

  2. Mode match

    The existing property/listing mode rule must match scope.IsTest. Partner requests are live-only.

  3. Origin match

    When scope.PartnerID is present, the property’s origin_partner_id must match it. Rental-app properties and properties from another partner are invisible.

Use P3’s explicit port.LandlordScope and existing handler scope-construction convention. Do not hide repository authorisation in context values or introduce a second scope type. Landlord v1 has no partner ID and keeps its existing live/test visibility.

Thread and write gates

  • PeekMessages and GetOwnerMessage resolve the parent through the scoped reader before reading messages; replay retains the message-to-thread membership check.
  • The action helper resolves with the full scope before confirm/counter/decline and uses the same scope for its refreshed response. Message posting performs the same scoped check before sending.
  • Existing use cases enforce ownership, valid transitions, thread writability, message validation, and lifecycle rules.
  • Origin is immutable: no new property-origin mutation or locking policy, and no new enquiry archive policy.
  • Migrate every affected caller and test double to the explicit scope. No legacy-signature aliases or compatibility wrappers; portal workflows otherwise remain unchanged.

Messages, attribution, and idempotency

Identity and channel

Sender
The landlord remains SenderUserID.
API channel
Extend stamping to partner actors for ordinary messages and action-generated system messages: sent_via: "api". Normal session messages keep existing behaviour.
Tenant disclosure
Keep existing tenant/landlord assistant disclosure driven by the API marker. No partner-specific branding or sender role.
Audit
Record the actual partner through the existing partner audit mechanism. Keep the partner actor in context; do not convert it to api_key just to obtain stamping.
Read side effects
Message GETs and single-message replay lookup never mark messages read.

Message-post retries

Reuse the existing executor and scopedIdempotencyKey so one partner key can reuse a client key across landlords without collision. Preserve method, path, raw-body fingerprinting, and resource-type semantics.

CaseResponse
First successful post201.
Matching replayOriginal message, 200, Idempotent-Replay: true.
Conflicting key reuseExisting 409 response.
No idempotency headerExisting ordinary message-post behaviour.
Authentication, grant, and parent visibility run before new execution or replay. The replay message must belong to the scoped thread
Authentication, grant, and parent visibility run before new execution or replay. The replay message must belong to the scoped thread.

Viewing actions keep existing v1 retry behaviour, including unchanged confirmation of an already-confirmed identical time. Add no new idempotency-header requirement or background retry system.

Errors and lifecycle

Hidden viewing request or thread
404 viewing_request_not_found.
Hidden offer
404 offer_not_found.
Error source
Existing codes in adapter/inbound/http/enquiry_error_mapper.go; reuse v1 enquiry rendering and partner auth/grant errors.
Validation and transitions
Existing status codes and error bodies remain unchanged. No new not-found codes.
History and writes
Archived history remains readable; writes follow existing rental workflow rules, not a blanket archive restriction.

Verification and acceptance

  1. SQL list/detail isolation across landlords, partners, and test/live mode, including properties without partner origin.
  2. Pagination and totals include only visible matches even when hidden rows would otherwise fill the page; existing filters remain correct.
  3. Key ceiling and active grant are both required. Landlord creation cannot provision consent-only scopes; approved connect requests can.
  4. Viewing actions/messages work on authorised own-property requests and cannot affect foreign-property requests.
  5. Ordinary and action-generated messages carry sent_via: "api"; session behaviour stays unchanged and partner audit attribution is retained.
  6. Reads do not mark messages read. Replays return the original without duplication; conflicts fail; landlord-scoped keys are isolated; revoked or inaccessible replay cannot leak content.
  7. Offer reads work while offer actions remain unlisted. Landlord v1 live/test contracts remain unchanged.

Runtime and browser proof

Use the permitted test environment and isolated fixtures. Exercise a real approved grant through viewing list/detail, a viewing action, message post/replay, offer list/detail, and an inaccessible-property attempt.

Browser verification covers consent labels and panel scope selection under frontend browser rules. Verify all three locale mappings and representative rendered translations without tests that merely pin wording.

Contract documentation

Update the separate Partner OpenAPI and existing API documentation with routes, required scopes, property visibility, consent-only grants, attribution, and retries. Do not change landlord v1’s public contract.

Non-goals and delivery boundary

  • Offer creation/counter/accept/decline/withdrawal; tenant-side viewing operations; cancelling confirmed viewings.
  • Marking messages read; a separate inbox API; all-properties grants; new contact disclosure; partner-branded tenant UI.
  • Webhooks, sandbox mode, self-service signup, developer portal, and unrelated refactoring.