@acosmi/sdk-ts 1.4.2 → 1.5.1

package/docs/compliance.md

@@ -90,6 +90,17 @@ Report scopes are split by action:
   again) so the new scope is granted.
 - `ScopeComplianceReportsPublish` — `publishReport` (also requires step-up).
 
+Contract-template scopes (added in v1.5.0; originally planned as v1.10.0 — see
+CHANGELOG §"S5：合同模板") are split by direction and do not require step-up:
+
+- `ScopeComplianceContractTemplateRead` — `getContractTemplate`,
+  `listContractTemplates`, `listContractTemplateVersions`.
+- `ScopeComplianceContractTemplateWrite` — `createContractTemplate`,
+  `updateContractTemplate`, `deleteContractTemplate`,
+  `uploadContractTemplatePdf`, `publishContractTemplate`,
+  `archiveContractTemplate`. Tokens issued before v1.5.0 do **not** carry these
+  scopes; existing users must re-authorize so the new scopes are granted.
+
 ## Base URL
 
 `Client` keeps the existing model gateway path under `/api/v4`. Compliance uses
@@ -231,6 +242,403 @@ if (view.status === 'SUCCESS') {
 }
 ```
 
+## Paginated Lists
+
+Since v1.5.0 (originally planned as v1.6.0 — see CHANGELOG §"S1：6 个分页列表")
+the SDK exposes paginated list reads against the backend
+compliance gateway (`GET .../page`). Each returns a yudao `PageResult<T>`
+(`{ total, list }` — the single SDK-wide pagination result shape, an alias of
+`YudaoPageResult<T>`):
+
+```ts
+import type { PageResult, EvidenceAssetPageItem } from '@acosmi/sdk-ts';
+
+client.compliance.listEvidenceAssets(req?, signal?):    Promise<PageResult<EvidenceAssetPageItem>>;
+client.compliance.listTimestamps(req?, signal?):        Promise<PageResult<TimestampPageItem>>;
+client.compliance.listEvidencePackages(req?, signal?):  Promise<PageResult<EvidencePackagePageItem>>;
+client.compliance.listReports(req?, signal?):           Promise<PageResult<ReportPageItem>>;
+client.compliance.listSigningEnvelopes(req?, signal?):  Promise<PageResult<SigningEnvelopePageItem>>;
+client.compliance.listSealApprovals(req?, signal?):     Promise<PageResult<SealApprovalPageItem>>;
+client.compliance.listSealUses(req?, signal?):          Promise<PageResult<SealUsePageItem>>;
+```
+
+The request argument is optional. It extends the shared `PageRequest`
+(`pageNo`, `pageSize`, `sortBy`, `sortDirection` — all optional; omitted values
+let the backend pick defaults) plus per-method filters:
+
+| Method | Endpoint | Filters (all optional) |
+| --- | --- | --- |
+| `listEvidenceAssets` | `GET /compliance/evidence/assets/page` | `assetType`, `status`, `createTimeStart`, `createTimeEnd` |
+| `listTimestamps` | `GET /compliance/timestamps/page` | `provider`, `verificationStatus`, `createTimeStart`, `createTimeEnd` |
+| `listEvidencePackages` | `GET /compliance/evidence/packages/page` | `status`, `createTimeStart`, `createTimeEnd` |
+| `listReports` | `GET /compliance/reports/page` | `status`, `createTimeStart`, `createTimeEnd` |
+| `listSigningEnvelopes` | `GET /compliance/signing-envelopes/page` | `status`, `createTimeStart`, `createTimeEnd` |
+| `listSealApprovals` | `GET /compliance/seal-approvals/page` | `status`, `createTimeStart`, `createTimeEnd` |
+| `listSealUses` | `GET /compliance/seal-uses/page` | `sealId`, `envelopeId`, `usageStatus`, `createTimeStart`, `createTimeEnd` |
+
+`createTimeStart` / `createTimeEnd` are caller-supplied datetime **strings**. The
+backend parses them as `yyyy-MM-dd HH:mm:ss` (for example
+`'2026-05-01 00:00:00'`). The SDK passes them through verbatim — it does not
+validate the format or convert time zones.
+
+```ts
+const page = await client.compliance.listSealApprovals({
+  pageNo: 1,
+  pageSize: 20,
+  status: 'PENDING',
+  createTimeStart: '2026-05-01 00:00:00',
+  createTimeEnd: '2026-05-22 23:59:59',
+});
+
+console.log(page.total, page.list.length);
+```
+
+These are authenticated GET reads, so they follow the same read semantics as
+`getEvidenceAsset` / `getReport`: one safe `401` refresh-and-replay retry.
+
+`listSealApprovals` is distinct from `listPendingSealApprovals` — the latter
+returns only pending approvals as a plain array; `listSealApprovals` is paginated
+and supports status / time filtering.
+
+The `*PageItem` types (`EvidenceAssetPageItem`, `TimestampPageItem`,
+`EvidencePackagePageItem`, `ReportPageItem`, `SigningEnvelopePageItem`,
+`SealApprovalPageItem`, `SealUsePageItem`) are the SDK-safe subset of the
+corresponding detail view plus a `createTime` (ISO-8601) field. They never
+expose provider raw payloads, certificates, storage keys, or contract originals.
+
+`listSealUses` (compliance gateway S6) returns one row per **seal use** — the
+real `provider`-side seal application that fires after envelope / contract /
+seal / approval are linked. It is orthogonal to the envelope domain status and
+to the seal-approval workflow:
+
+- `listSigningEnvelopes` → high-level envelope domain state.
+- `listSealApprovals` → the approval workflow on an envelope (`PENDING` →
+  `APPROVED` / `REJECTED` / `CANCELED`).
+- `listSealUses` → the actual seal-application execution
+  (`invokedAt` → `consumedAt`, with `failureReason` on terminal failure).
+
+`SealUsePageItem` fields: `id` (number), `envelopeId` (number), `contractId`
+(number), `sealId` (number), `usageStatus` (string), `signLocationType`
+(string?), `invokedAt` (string?), `consumedAt` (string?), `failureReason`
+(string?), `createTime` (string — ISO-8601).
+
+`listSealUses` reuses the existing read scope
+`ScopeComplianceContractSigningRead` (`compliance:contract_signing:read`); it
+does not introduce a new scope. The seal authorization surface and the full
+seal CRUD (gap-register U-3 / U-11) remain backend-deferred behind the CFCA
+private jar and the W3 gate, and are not exposed as SDK methods in this
+release.
+
+## Capabilities And Operation Projection
+
+Since v1.5.0 (originally planned as v1.7.0 — see CHANGELOG §"S2：capabilities +
+operations 投影") the SDK exposes the compliance gateway S2 reads: a capability gate
+query and an operation-projection view.
+
+```ts
+client.compliance.getCapabilities(signal?):              Promise<ComplianceCapability[]>;
+client.compliance.getFeatureGate(action, signal?):       Promise<ComplianceCapability | undefined>;
+client.compliance.listOperations(req?, signal?):         Promise<PageResult<OperationPageItem>>;
+client.compliance.getOperation(id, signal?):             Promise<OperationDetail>;
+```
+
+All four are authenticated GET reads — they follow the same read semantics as
+`getReport` / `getEvidenceAsset`: one safe `401` refresh-and-replay retry.
+
+### Capabilities
+
+`getCapabilities` returns one `ComplianceCapability` entry per high-risk /
+billed action: `signEnvelope`, `createH5SigningUrl`, `publishReport`,
+`approveSealApproval`, `executeSealUse`, `createSeal`.
+
+```ts
+const caps = await client.compliance.getCapabilities();
+for (const cap of caps) {
+  console.log(cap.action, cap.executable, cap.state, cap.requiredScopes);
+}
+```
+
+`ComplianceCapability` fields: `action` (string), `executable` (boolean),
+`state` (`executable` / `scope_missing` / `not_provisioned` /
+`step_up_required` / `gate_closed` / `unknown` — reuses the cross-domain
+`FeatureGateState` open union), `requiredScopes` (string[]), `requiredStepUp`
+(boolean), `reason` (string).
+
+Query the capability **before** invoking a high-risk action and gate the UI on
+it. When the capability cannot be fetched, fail-closed — treat the action as
+`executable: false`.
+
+`getFeatureGate` is a convenience that fetches `getCapabilities` and returns the
+entry whose `action` matches (or `undefined` when none match). **Each call makes
+one network request.** To gate several actions, call `getCapabilities` once and
+look them up locally instead of calling `getFeatureGate` repeatedly.
+
+```ts
+const gate = await client.compliance.getFeatureGate('publishReport');
+if (!gate || !gate.executable) {
+  if (gate?.state === 'step_up_required') {
+    await promptUserToReauthenticate();
+  }
+  return; // fail-closed
+}
+```
+
+### Operation Projection
+
+The operation projection describes the progress of a single operation — it is
+orthogonal to a fulfillment object's domain status.
+
+```ts
+const page = await client.compliance.listOperations({
+  pageNo: 1,
+  pageSize: 20,
+  status: 'failed',
+  createTimeStart: '2026-05-01 00:00:00',
+  createTimeEnd: '2026-05-22 23:59:59',
+});
+
+for (const op of page.list) {
+  console.log(op.id, op.operationId, op.status, op.terminal, op.retryable);
+}
+
+const detail = await client.compliance.getOperation(page.list[0].id);
+```
+
+`listOperations` (`GET /compliance/operations/page`) returns a yudao
+`PageResult<OperationPageItem>`. Its request extends the shared `PageRequest`
+plus the optional `status` / `createTimeStart` / `createTimeEnd` filters.
+`getOperation` (`GET /compliance/operations/{id}`) takes the numeric **row id**
+(not the `operationId` idempotency key) and returns `OperationDetail`.
+
+`OperationPageItem` / `OperationDetail` fields: `id` (number), `operationId`
+(string — the idempotency key), `status` (string), `terminal` (boolean),
+`retryable` (boolean), `attemptCount` (number), `businessNo` (string?),
+`contractNo` (string?), `sealId` (number?), `reconciliationStatus` (string?),
+`nextRetryAt` (string?), `requestedAt` (string?), `respondedAt` (string?),
+`createTime` (string). Time fields are ISO-8601. These views never expose
+provider raw payloads, certificates, storage keys, or contract originals.
+
+`createTimeStart` / `createTimeEnd` are caller-supplied datetime strings parsed
+by the backend as `yyyy-MM-dd HH:mm:ss`; the SDK passes them through verbatim.
+
+## TSA Readonly Views
+
+Since v1.5.0 (originally planned as v1.8.0 — see CHANGELOG §"S3：TSA readonly
+视图") the SDK exposes the compliance gateway S3 reads: two timestamp
+authority (TSA) readonly views.
+
+```ts
+client.compliance.listTsaProviders(signal?):  Promise<TsaProvider[]>;
+client.compliance.getTsaStats(signal?):       Promise<TsaStats>;
+```
+
+Both are authenticated GET reads — they follow the same read semantics as
+`getReport` / `getCapabilities`: one safe `401` refresh-and-replay retry.
+
+`listTsaProviders` (`GET /compliance/timestamps/providers`) returns one
+`TsaProvider` entry per configured TSA provider.
+
+```ts
+const providers = await client.compliance.listTsaProviders();
+for (const p of providers) {
+  console.log(p.name, p.environment, p.available);
+}
+```
+
+`TsaProvider` fields: `name` (string), `environment` (string — for example
+`production` / `sandbox`), `available` (boolean). It is a readonly view — it
+never exposes provider endpoints, credentials, certificates, or other internal
+integration material.
+
+`getTsaStats` (`GET /compliance/timestamps/stats`) returns a readonly
+aggregation: the total timestamp count plus a per-verification-status count map.
+
+```ts
+const stats = await client.compliance.getTsaStats();
+console.log(stats.total);
+console.log(stats.byVerificationStatus.VERIFIED ?? 0);
+```
+
+`TsaStats` fields: `total` (number), `byVerificationStatus`
+(`Record<string, number>` — keys are verification-status enum names such as
+`VERIFIED` / `PENDING` / `FAILED`, values are counts). The map may be empty
+when no timestamps exist.
+
+## Envelope Completion
+
+Since v1.5.0 (originally planned as v1.9.0 — see CHANGELOG §"S4：envelope 收尾
++ void") the SDK exposes the compliance gateway S4 envelope-completion
+surface: two readonly views and one write.
+
+```ts
+client.compliance.listEnvelopeContracts(envelopeId, signal?):         Promise<EnvelopeContractItem[]>;
+client.compliance.listEnvelopeProviderRequests(envelopeId, signal?):  Promise<OperationPageItem[]>;
+client.compliance.voidEnvelope(envelopeId, req, options?):            Promise<boolean>;
+```
+
+`listEnvelopeContracts` (`GET /compliance/signing-envelopes/{id}/contracts`)
+and `listEnvelopeProviderRequests`
+(`GET /compliance/signing-envelopes/{id}/provider-requests`) are authenticated
+GET reads — they follow the same read semantics as `getReport` /
+`getCapabilities`: one safe `401` refresh-and-replay retry. Both return a plain
+array (not a `PageResult`).
+
+```ts
+const contracts = await client.compliance.listEnvelopeContracts(envelopeId);
+for (const c of contracts) {
+  console.log(c.contractNo, c.title, c.status, c.contentHash);
+}
+
+const providerRequests =
+  await client.compliance.listEnvelopeProviderRequests(envelopeId);
+for (const op of providerRequests) {
+  console.log(op.operationId, op.status, op.terminal, op.retryable);
+}
+```
+
+`EnvelopeContractItem` fields: `id` (number), `envelopeId` (number),
+`contractNo` (string), `title` (string), `mimeType` (string), `size` (number),
+`hashAlgorithm` (string), `contentHash` (string), `signedContentHash`
+(string?), `status` (string), `createTime` (string — ISO-8601). It is a
+SDK-safe view — it never exposes contract originals, storage keys, or provider
+raw payloads.
+
+`listEnvelopeProviderRequests` **reuses** the operation-projection type
+`OperationPageItem` (see *Capabilities And Operation Projection*); it describes
+the progress of each provider request, orthogonal to the envelope's domain
+status.
+
+`voidEnvelope` (`POST /compliance/signing-envelopes/{id}/void`) is a **write**.
+It follows the compliance write rules — it accepts the `Idempotency-Key`
+header, does not auto-retry on 5xx / timeouts, and does not refresh/replay on
+`401`. The void reason is required and is sent in the JSON body:
+
+```ts
+const voided = await client.compliance.voidEnvelope(
+  envelopeId,
+  { reason: 'signed in error' },
+  { idempotencyKey: voidKey },
+);
+```
+
+`VoidEnvelopeRequest` is `{ reason: string }`. Persist the idempotency key on
+the caller side and reuse it when resuming the same void action.
+
+Envelope completion actions beyond this S4 subset — send, remind, authorize,
+download, and token — are deferred backend-side and are not exposed as SDK
+methods in this release.
+
+## Contract Templates
+
+Since v1.5.0 (originally planned as v1.10.0 — see CHANGELOG §"S5：合同模板")
+the SDK exposes the compliance gateway S5 contract-template
+surface: a `DRAFT` → `PUBLISHED` → `ARCHIVED` lifecycle with PDF upload, field
+overlay, and immutable version snapshots.
+
+```ts
+client.compliance.createContractTemplate(req, options?):                Promise<ContractTemplateResp>;
+client.compliance.updateContractTemplate(id, req, options?):            Promise<ContractTemplateResp>;
+client.compliance.deleteContractTemplate(id, options?):                 Promise<void>;
+client.compliance.getContractTemplate(id, signal?):                     Promise<ContractTemplateResp>;
+client.compliance.listContractTemplates(req?, signal?):                 Promise<PageResult<ContractTemplatePageItem>>;
+client.compliance.uploadContractTemplatePdf(id, req, options?):         Promise<ContractTemplateResp>;
+client.compliance.publishContractTemplate(id, options?):                Promise<ContractTemplateResp>;
+client.compliance.archiveContractTemplate(id, options?):                Promise<ContractTemplateResp>;
+client.compliance.listContractTemplateVersions(id, signal?):            Promise<ContractTemplateVersion[]>;
+```
+
+Lifecycle:
+
+```ts
+// 1) Create in DRAFT.
+const tpl = await client.compliance.createContractTemplate(
+  { name: 'Mutual NDA', description: 'standard NDA' },
+  { idempotencyKey: createKey },
+);
+
+// 2) Upload PDF body (base64-encoded). pdfHash / pdfPageCount come back on the
+// returned ContractTemplateResp.
+const withPdf = await client.compliance.uploadContractTemplatePdf(
+  tpl.id,
+  { pdfBase64: readPdfBase64() },
+  { idempotencyKey: uploadKey },
+);
+
+// 3) Edit the field overlay (signatures / seals / text / date / check). Only
+// allowed while the template is still DRAFT.
+await client.compliance.updateContractTemplate(
+  tpl.id,
+  {
+    fields: [
+      {
+        key: 'sig-partyA',
+        type: 'signature',
+        label: 'Party A signature',
+        page: 1,
+        x: 100,
+        y: 200,
+        width: 80,
+        height: 30,
+        assignedRole: 'partyA',
+        order: 0,
+        required: true,
+      },
+    ],
+  },
+  { idempotencyKey: updateKey },
+);
+
+// 4) Publish — DRAFT → PUBLISHED. currentVersion increments and the fields +
+// pdfHash are frozen into the version table.
+const published = await client.compliance.publishContractTemplate(tpl.id, {
+  idempotencyKey: publishKey,
+});
+
+// 5) Optionally archive a published template — PUBLISHED → ARCHIVED. Archived
+// templates are read-only.
+await client.compliance.archiveContractTemplate(tpl.id, {
+  idempotencyKey: archiveKey,
+});
+```
+
+`createContractTemplate`, `updateContractTemplate`, `deleteContractTemplate`,
+`uploadContractTemplatePdf`, `publishContractTemplate`, and
+`archiveContractTemplate` are **writes**. They follow the compliance write
+rules — they accept the `Idempotency-Key` header, do not auto-retry on 5xx /
+timeouts, and do not refresh/replay on `401`. Persist the idempotency key on
+the caller side and reuse it when resuming the same action (especially
+`uploadContractTemplatePdf`, which costs bandwidth to retry).
+
+`updateContractTemplate` and `deleteContractTemplate` are **DRAFT-only**. The
+backend refuses both on `PUBLISHED` / `ARCHIVED` templates — for a published
+template, switch to `archiveContractTemplate` instead of deleting it.
+
+`uploadContractTemplatePdf` takes `{ pdfBase64 }` in the request body. The SDK
+does not parse the PDF, validate geometry, or compute the hash on the
+client — those happen on the backend. `pdfHash` and `pdfPageCount` come back on
+the returned `ContractTemplateResp`.
+
+`getContractTemplate`, `listContractTemplates`, and
+`listContractTemplateVersions` are authenticated GET reads — they follow the
+same read semantics as `getReport` / `getCapabilities`: one safe `401`
+refresh-and-replay retry.
+
+`listContractTemplates` returns a `PageResult<ContractTemplatePageItem>`. The
+list-item view deliberately omits `fields` to avoid large-object N+1 on the
+list endpoint — the field overlay is only present on the detail
+(`ContractTemplateResp`) and on each version snapshot
+(`ContractTemplateVersion`).
+
+`listContractTemplateVersions` returns a plain array (not a `PageResult`).
+Every `publishContractTemplate` call appends one immutable
+`ContractTemplateVersion` — capturing the template's `name`, `pdfHash`,
+`fields`, and `statusAtSnapshot` at publish time — and is the offline-review
+ground truth for the version.
+
+The 9 methods do **not** require step-up. They require the new
+`ScopeComplianceContractTemplateRead` (reads) or
+`ScopeComplianceContractTemplateWrite` (writes) scope.
+
 ## Error Classification
 
 Compliance business errors are returned as numeric Java error codes in the
@@ -252,6 +660,16 @@ switch (info.key) {
 `CompliancePollError` is used by polling helpers for terminal failure, timeout,
 abort, and unknown states.
 
+Since v1.5.0, `complianceErrorToRetryAdvice(info)` projects a `ComplianceErrorInfo`
+into the cross-domain `RetryAdvice` model (`retryable` / `retryAfter` /
+`sameIdempotencyKeyRequired` / `manualActionRequired` / `reason` / messages /
+`supportCode`). It is an additive, read-only projection — it does not modify or
+replace `ComplianceErrorInfo`; `classifyComplianceError` is unchanged. The
+`reason` field is a normalized mapping of the existing error-code registries, not
+a new code set. Terminal errors advise a fresh idempotency key
+(`sameIdempotencyKeyRequired: false`); step-up errors advise re-authenticating
+and retrying with the same key.
+
 ## Method Status
 
 Each `client.compliance.*` method has one of four maturity grades. Treat this
@@ -261,9 +679,9 @@ for them.
 
 | Status | Methods | Meaning |
 | --- | --- | --- |
-| `production-ready` | `createEvidenceAsset`, `getEvidenceAsset`, `verifyEvidencePublic`, `issueTimestamp`, `issueTimestampForAsset`, `getTimestamp`, `verifyTimestamp`, `waitForTimestampVerified`, `buildEvidencePackage`, `createReport`, `getReport`, `downloadReport`, `createSigningEnvelope`, `getSigningEnvelope`, `syncSigningEnvelopeStatus`, `submitSealApproval`, `rejectSealApproval`, `cancelSealApproval`, `listPendingSealApprovals`, `getSealApproval`, `getProviderRequest`, `waitForProviderRequestTerminal`, `classifyError` | Backend endpoint, scope, DTO contract, SDK tests and docs are all closed. Safe to call in production. |
+| `production-ready` | `createEvidenceAsset`, `getEvidenceAsset`, `verifyEvidencePublic`, `listEvidenceAssets`, `listEvidencePackages`, `issueTimestamp`, `issueTimestampForAsset`, `getTimestamp`, `verifyTimestamp`, `waitForTimestampVerified`, `listTimestamps`, `listTsaProviders`, `getTsaStats`, `buildEvidencePackage`, `createReport`, `getReport`, `downloadReport`, `listReports`, `createSigningEnvelope`, `getSigningEnvelope`, `syncSigningEnvelopeStatus`, `listSigningEnvelopes`, `listEnvelopeContracts`, `listEnvelopeProviderRequests`, `voidEnvelope`, `createContractTemplate`, `updateContractTemplate`, `deleteContractTemplate`, `getContractTemplate`, `listContractTemplates`, `uploadContractTemplatePdf`, `publishContractTemplate`, `archiveContractTemplate`, `listContractTemplateVersions`, `submitSealApproval`, `rejectSealApproval`, `cancelSealApproval`, `listPendingSealApprovals`, `getSealApproval`, `listSealApprovals`, `listSealUses`, `getProviderRequest`, `waitForProviderRequestTerminal`, `getCapabilities`, `getFeatureGate`, `listOperations`, `getOperation`, `classifyError` | Backend endpoint, scope, DTO contract, SDK tests and docs are all closed. Safe to call in production. |
 | `gated` | `publishReport`, `signEnvelope`, `createH5SigningUrl`, `approveSealApproval` | SDK exposes the method, but the backend fails-closed (`COMPLIANCE_STEP_UP_REQUIRED` / `ENVELOPE_GATE_CLOSED`) until step-up and the W3 gate chain are ready. The SDK does not retry and does not fake success — surface the typed error as "feature not yet open". |
-| `draft contract` | operation views, gate-status views, binary download helpers | Type drafts only — not exposed as callable capability in this release. |
+| `draft contract` | binary download helpers | Type drafts only — not exposed as callable capability in this release. |
 | `internal-only` | distribution billing (`reserve` / `commit` / `cancel` / `reconcile` / `refund`), provider raw payloads, provider callbacks, CFCA controlled materials | Server-side S2S only. Never part of the SDK call surface; no SDK method exists for these. |
 
 `submitSealApproval` is `production-ready`: the backend enforces
@@ -271,6 +689,43 @@ for them.
 with the same key returns the original approval id instead of creating a
 duplicate. Persist the idempotency key on the caller side.
 
+`getCapabilities`, `getFeatureGate`, `listOperations`, and `getOperation` are
+`production-ready` against the compliance gateway S2 (`G2`) contract — endpoint,
+DTO, SDK tests, and docs are closed. They are read-only GET projections and do
+not themselves carry step-up or gate state; `getCapabilities` *reports* whether
+the gated actions are currently executable.
+
+`listTsaProviders` and `getTsaStats` are `production-ready` against the
+compliance gateway S3 (`G3`) contract — endpoint, DTO, SDK tests, and docs are
+closed. They are read-only GET projections of timestamp authority state and
+aggregate counts; they carry no step-up or gate state.
+
+`listEnvelopeContracts`, `listEnvelopeProviderRequests`, and `voidEnvelope` are
+`production-ready` against the compliance gateway S4 (`G4`) contract — endpoint,
+DTO, SDK tests, and docs are closed. The two `list*` methods are read-only GET
+projections; `voidEnvelope` is a write that accepts `Idempotency-Key`, does not
+auto-retry, and does not refresh/replay on `401`. Send / remind / authorize /
+download / token actions are deferred backend-side and have no SDK method.
+
+The 9 contract-template methods — `createContractTemplate`,
+`updateContractTemplate`, `deleteContractTemplate`, `getContractTemplate`,
+`listContractTemplates`, `uploadContractTemplatePdf`,
+`publishContractTemplate`, `archiveContractTemplate`,
+`listContractTemplateVersions` — are `production-ready` against the compliance
+gateway S5 (`G5`) contract: endpoint, DTO, SDK tests, and docs are closed. Reads
+are GET (one safe `401` refresh-and-replay); writes accept `Idempotency-Key`,
+do not auto-retry, and do not refresh/replay on `401`. None of them require
+step-up. `updateContractTemplate` and `deleteContractTemplate` are
+DRAFT-only — the backend refuses both on `PUBLISHED` / `ARCHIVED` templates.
+
+`listSealUses` is `production-ready` against the compliance gateway S6 (`G6`)
+contract — endpoint, DTO, SDK tests, and docs are closed. It is a read-only
+GET projection (one safe `401` refresh-and-replay) and reuses the existing
+`ScopeComplianceContractSigningRead` scope; no new scope is introduced. The
+broader seal authorization layer and seal CRUD surface (gap-register U-3 /
+U-11) remain backend-deferred behind the CFCA private jar and the W3 gate;
+they are intentionally **not** exposed as SDK methods in this release.
+
 ## Safety Boundary
 
 Do not place any of the following in SDK code, tests, examples, docs, git

package/examples/auth-oauth-flow.ts

@@ -11,8 +11,12 @@
 // 说明：
 //   - 大多数场景直接用 `client.login(appName, scopes)` 即可（内部封装了下面全部步骤）。
 //     本示例演示底层 helper，适用于需要自定义授权流程 / 自管 token 的 CLI。
-//   - authorize 仅在 Node 环境可用（需要本地 HTTP 回调 server）；浏览器侧应自行实现
-//     popup window + redirect handler。
+//   - authorize 仅在 Node 环境可用（需要本地 HTTP 回调 server）。
+//   - 浏览器侧（无 loopback server）请改用 v1.4.0+ Web OAuth 原语：
+//     discoverWebOAuthMetadata + registerWebOAuthClient +
+//     createWebAuthorizationRequest + completeWebAuthorizationRequest，
+//     由调用方实现 popup / 同窗口 redirect handler，SDK 负责 PKCE / state 校验 / token 兑换。
+//     浏览器 token 刷新可配 Config.browserRefreshMode / refreshProxyURL (v1.4.1+) 规避 issuer CORS 403。
 
 import {
   discover,

package/examples/compliance-evidence-timestamp.ts

@@ -22,6 +22,7 @@ import {
   ScopeComplianceTimestampIssue,
   ScopeComplianceTimestampVerify,
   ScopeComplianceReportsRead,
+  ScopeComplianceReportsWrite,
 } from '@acosmi/sdk-ts';
 
 // 模拟持久化的 Idempotency-Key 存储；生产环境应落 DB / 本地文件 / 业务订单表。
@@ -51,7 +52,8 @@ async function main() {
     ScopeComplianceEvidenceWrite,
     ScopeComplianceTimestampIssue,
     ScopeComplianceTimestampVerify,
-    ScopeComplianceReportsRead,
+    ScopeComplianceReportsRead,   // getReport / downloadReport
+    ScopeComplianceReportsWrite,  // createReport（v1.3.2 起从 read 切到独立 write scope）
   ]);
 
   // 1) 本地 sha256 (用户业务内容)

package/examples/core-chat.ts

@@ -8,9 +8,12 @@
 //   5. 流式 chatStreamWithUsage 并聚合 usage / 结算事件
 //
 // 说明：
-//   - SDK 自动按 ManagedModel 的 preferredFormat / supportedFormats 选 Anthropic
-//     或 OpenAI adapter，调用方无需关心。
+//   - SDK 自动按 ManagedModel 的 preferred_format / supported_formats（snake_case
+//     wire 字段）选 Anthropic 或 OpenAI adapter，调用方无需关心。详见
+//     src/models/adapters/index.ts:getAdapterForModel。
 //   - 金额 / 余额字段是 string（避免 JS number 精度损失），不要做浮点运算。
+//   - ChatRequest 走 snake_case wire 字段（max_tokens 等），与上游 Go json tag 对齐；
+//     ManagedModel 顶层多为 camelCase（modelId / isEnabled / inputModalities）。
 
 import { Client, allScopes, FileTokenStore } from '@acosmi/sdk-ts';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acosmi/sdk-ts",
-  "version": "1.4.2",
+  "version": "1.5.1",
   "description": "Acosmi TypeScript SDK：模型网关、Agent Run Gateway 与 Compliance（电子证据、时间章、报告、签署 envelope）统一客户端，支持浏览器 / Node ≥18 / Deno / Bun。",
   "type": "module",
   "main": "./dist/node/index.cjs",