Repository navigation
facta-dte/api v0.2.0-rc.1
Pre-release
Pre-release
·
10 commits
to main
since this release
Release candidate. Tagged as a pre-release: Composer's default stable stability and constraints such as ^0.1 do not select it. Install it explicitly with composer require facta-dte/api:0.2.0-rc.1. The stable release stays at 0.1.0 until the shared data key is in production. The notes below are the planned 0.2.0 notes.
The shared data key: the server resolves catalogue ids and reads the catalogue in every mode, so the
SDK carries no copy of it. Follows the TypeScript SDK 0.6.0.
Changed
- Catalogue reads always call the API (
listCustomers()...searchProducts()). They no longer
read/v1/statusfirst, no longer needunlockKey, and no longer throwunauthorized
(local_snapshot_unsupported/unlock_key_missing) for a company whose catalogue is encrypted at rest. customerId/productIdinissue()andprepare()travel untouched. The same gate no
longer refuses them. An unknown id is the server'snot_found(details.reasoncatalog_unknown_id).- No
X-Facta-Request-Fingerprintheader onissue()/prepare(): the SDK does not rewrite the
body, so the server's idempotency claim hashes it.Json\Fingerprintstays for other uses. diagnose()no longer reports acatalog-synccheck. The guidance ofcatalog_encryptedno longer
says the catalogue can be read with the unlock key.
Added
- Error codes the server now returns:
catalog_revision_conflict,catalog_record_inactive,
catalog_search_too_broad,catalog_cursor_expired,data_grant_unavailable,data_grant_revoked,
data_epoch_stale,inbox_retired(constants onFactaError). - Drafts (scope
draft):createDraft(),listDrafts(),getDraft(),getDraftByKey(),updateDraft()(versionsent asIf-Match),cancelDraft()andissueDraft()(carries the sign key, answers likeissue()plusborradorId). Constants for the draft codes (DRAFTS_NOT_READY,VERSION_MISMATCH,DRAFT_CLAIMED,DRAFT_ISSUING,DRAFT_ISSUED,DRAFT_NOT_ISSUABLE,ITEM_FINAL,ID_CONFLICT,INBOX_CAP_REACHED,CONTENT_HASH_MISMATCH,CATALOG_WRITE_TEST_KEY). - Every code the server can answer is a
FactaErrorconstant, includingMH_AUTH_FAILED(424),PAID_PLAN_REQUIRED(402) and the Drive broker codes.CATALOG_SNAPSHOT_RETIREDis removed: the server never sent it. tests/ContractParityTest.phppins the SDK to a snapshot of the staging contract (tests/fixtures/openapi.yaml): error codes both ways, the retry set (the TypeScript one) and every route wrapped or deliberately not wrapped.ifMatchoption onupdateCustomer()/updateProduct(), andrevisionon single catalogue records
read or written on a company that shares its data key (fromFacta-Catalog-Revision/ETag).listCatalogChanges()forGET /v1/catalog/changes?since=.FactaError::WEBHOOK_LIMIT_REACHED,WEBHOOK_DUPLICATE;Webhook::EVENTS;WebhookVerificationError(withgetReason()) thrown byWebhook::constructEvent().data_grant_unavailableanddata_epoch_stale(503) are retried like the other transient codes;data_grant_revoked(403) is final.- Webhooks:
createWebhook(),listWebhooks(),getWebhook(),updateWebhook(),deleteWebhook(),
rotateWebhookSecret(),testWebhook(), and the receiver-sideWebhook::verify()/
Webhook::constructEvent()/Webhook::sign()withWebhookReplayStore/MemoryWebhookReplayStore.