@capxul/sdk 0.1.0-alpha.4 → 0.1.0-alpha.6

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @capxul/sdk
 
+## 0.1.0-alpha.6
+
+### Minor Changes
+
+- 57203a4: Withdrawals v1 W2 (#465) — public surface tightening + org-scope create
+  - `WithdrawalsCreateInput.destination` no longer accepts `kind`. The
+    backend now resolves the `external_account` row by FK and infers
+    the kind + rail server-side. Anything that doesn't route to
+    `chain_wallet` (or is chain_wallet but non-EVM in slice 1) returns
+    `VERIFICATION_REQUIRED` with `details.rail` + `details.currentKind`.
+  - `organizations.withdrawals.create` is now a real mutation (no
+    longer a `NOT_IMPLEMENTED` stub). Returns the `processing` row
+    only — Safe + Zodiac submission orchestration ships in W3+.
+  - `Errors.verificationRequired({ rail, currentKind })` factory
+    added; the `VERIFICATION_REQUIRED` code now broadens to cover
+    both KYC tier gates and unsupported withdrawal rails.
+
+  **Migration:** Remove `destination.kind` from any
+  `capxul.withdrawals.create({ destination: { kind, externalAccountId } })`
+  call sites. Pass only `externalAccountId`.
+
+## 0.1.0-alpha.5
+
+### Patch Changes
+
+- Version sync with `@capxul/sdk-react@0.1.0-alpha.5`; no headless SDK runtime
+  changes.
+
 ## 0.1.0-alpha.4
 
 ### Minor Changes

package/README.md

@@ -90,7 +90,7 @@ capxul.accounts      // create, retrieve, list
 capxul.organizations // CRUD + members + payments + treasury
 capxul.payments      // create, retrieve, list
 capxul.invoices      // create, retrieve, list
-capxul.withdrawals   // request, retrieve, list
+capxul.withdrawals   // create, retrieve, list
 capxul.documents     // KYC uploads, invoices, receipts, tax forms
 capxul.flows.{auth, onboarding, provisioning} // XState v5 flows
 ```

package/dist/{client-CcCtq5XO.d.ts → client-ChfXWMzO.d.ts}

@@ -2,7 +2,7 @@ import { Account as Account$1 } from 'viem';
 import { AnyStateMachine } from 'xstate';
 import { A as AccountId, S as SafeId, c as KycProfileId, b as ExternalAccountId, f as SubAccountId, d as OrganizationId, a as ApiKeyId, X as TimestampIso, D as DocumentId, O as OperationId, P as PaymentId, g as TransferId, k as WithdrawalId, W as WebhookEndpointId, j as WebhookEventId, M as MemberId, K as KybProfileId, V as VirtualAccountId, i as VirtualCardId } from './next-action-DkrwXYay.js';
 import { d as CapxulResult, C as CapxulError } from './errors-QHD5Tlok.js';
-import { A as Account, U as UserIdentifier, a as AccountLookupResult, S as Safe, i as KycProfile, E as ExternalAccount, L as List, v as SubAccount, B as BalanceLedgerEntry, b as ApiKey, D as Document, O as Operation, l as OperationStatus, k as Money, C as CreatePaymentResult, o as Payment, F as TransferEndpoint, f as CreateTransferResult, y as Transfer, g as CreateWithdrawalResult, _ as Withdrawal, Y as WebhookEndpoint, Z as WebhookEvent, n as Organization, J as Treasury, M as Member, K as KybProfile, V as VirtualAccount, Q as VirtualCard } from './types-75UokagF.js';
+import { A as Account, U as UserIdentifier, a as AccountLookupResult, S as Safe, i as KycProfile, E as ExternalAccount, L as List, v as SubAccount, B as BalanceLedgerEntry, b as ApiKey, D as Document, O as Operation, l as OperationStatus, k as Money, C as CreatePaymentResult, o as Payment, F as TransferEndpoint, f as CreateTransferResult, y as Transfer, g as CreateWithdrawalResult, _ as Withdrawal, Y as WebhookEndpoint, Z as WebhookEvent, n as Organization, J as Treasury, M as Member, K as KybProfile, V as VirtualAccount, Q as VirtualCard } from './types-CYvLP5pP.js';
 import * as types from '@repo/api-contract/gen/types';
 
 /**
@@ -282,8 +282,20 @@ type OrgDocumentsClient = {
  * Per sdk-surface.md §1a, `external_account` is a reusable withdrawal
  * destination. `create` + `list` live under the owner's nested
  * namespace (Pattern A — `accounts.externalAccounts.*` or
- * `organizations.externalAccounts.*`). `retrieve` and `remove` work by
- * ID without scoping.
+ * `organizations.externalAccounts.*`). The top-level `retrieve` and
+ * `remove` keep PERSONAL-scope semantics — for org rows route via
+ * the `organizations.externalAccounts.*` namespace which carries
+ * `organizationId` end-to-end and pins the row's owner pair to
+ * prevent cross-org IDOR (revision 1, #464).
+ *
+ * Withdrawals v1 W1 (#464) wires these stubs through the
+ * `externalAccounts/{queries,mutations}` Convex domain. The wire shape
+ * matches OpenAPI: `{ object: "external_account", id, kind, status,
+ * ..., operation: { id, status, correlationId } }` — the trust-chain
+ * ids live under the canonical nested `operation: OperationSummary`
+ * envelope (revision 3, #464), matching Withdrawal / Payment /
+ * Transfer / Organization. The SDK rebrands `id` + the nested
+ * `operation` sub-ids at the read edge.
  */
 
 type RetrieveCodes$b = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
@@ -473,35 +485,25 @@ type OrgTransfersClient = {
 
 /**
  * Withdrawals domain — funds exit Capxul via an `external_account` per
- * sdk-surface.md §1a + §4.52 + withdrawal-orchestration.mdx (slice 1
- * of Withdrawals v1, #440).
- *
- * Slice 1 NOTE — transitional input shape:
- * Until the `external_accounts` resource lands (slice 1.x or v2), the
- * destination input includes a `kind` field so the backend + SDK can
- * route to the chain_wallet rail without a real external_accounts
- * lookup. When the resource lands, `kind` becomes optional / ignored
- * and the kind is inferred from the resolved row.
+ * sdk-surface.md §1a + §4.52 + withdrawal-orchestration.mdx.
  *
- * Slice 1 NOTE — chain_wallet rail integration:
- * For evm destinations, the `externalAccountId` is treated as the
- * destination address (must start with `0x`) so the chain_wallet rail
- * can call `transferAsOwner` directly. For solana / starknet the SDK
- * accepts the create call but does NOT execute the rail submission —
- * the row stays in `processing` until external_accounts lands. The
- * caller can transition it via `markFailed` if needed.
+ * Withdrawals v1 W2 (#465) refactor:
+ * - The `kind` shim on `destination` is GONE. The backend now resolves
+ *   the destination row by FK and infers kind + rail. Anything that
+ *   doesn't route to `chain_wallet` returns `VERIFICATION_REQUIRED`.
+ * - Org-scope `create` is now a real mutation (no longer a stub).
+ *   Personal-scope keeps the on-chain submission tail; org-scope
+ *   returns the `processing` row only — Safe + Zodiac orchestration
+ *   ships in W3+ (D6).
+ * - All raw `try/catch` blocks have been replaced with `tryCatch` from
+ *   `@repo/observability`, mirroring `core/external-accounts.ts`
+ *   (precedent D2).
  */
 
 type WithdrawalsCreateInput = {
     readonly amount: Money;
     readonly destination: {
         readonly externalAccountId: ExternalAccountId;
-        /**
-         * Slice 1 transitional field. Required until the
-         * `external_accounts` resource lands; will become optional / ignored
-         * when the resource is the source of truth for kind.
-         */
-        readonly kind: "evm" | "solana" | "starknet" | "bank" | "momo" | "card_payout";
     };
     readonly source?: {
         readonly subAccountId: SubAccountId;
@@ -514,6 +516,22 @@ type WithdrawalsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
 };
+/**
+ * Withdrawals v1 W4 (#467) — input for the reconciliation pipe.
+ * Caller passes the same `txHash` that `recordSubmitted` wrote; the
+ * backend cross-checks the value against the persisted operation row.
+ *
+ * `withdrawalId` accepts either the branded `WithdrawalId` or a raw
+ * string. `txHash` is a raw string at the SDK boundary — the backend
+ * re-validates the shape via `toTxHash` at the mutation handler (the
+ * SDK package is no longer coupled to `@repo/types`'s brand surface
+ * post the alpha-epic decoupling; see
+ * `packages/sdk/docs/internal/decoupling-prep.md`).
+ */
+type WithdrawalsRecordCompletedInput = {
+    readonly withdrawalId: WithdrawalId | string;
+    readonly txHash: string;
+};
 type OrgWithdrawalsCreateInput = WithdrawalsCreateInput & {
     readonly organizationId: OrganizationId;
 };
@@ -526,13 +544,35 @@ type OrgWithdrawalsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
 };
-type CreateCodes$4 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "INSUFFICIENT_BALANCE" | "IDEMPOTENCY_CONFLICT" | "KYC_REQUIRED" | "POLICY_DENIED" | "RATE_LIMITED" | "NETWORK_ERROR";
+type CreateCodes$4 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "INSUFFICIENT_BALANCE" | "IDEMPOTENCY_CONFLICT" | "KYC_REQUIRED" | "POLICY_DENIED" | "RATE_LIMITED" | "NETWORK_ERROR" | "NOT_FOUND" | "VERIFICATION_REQUIRED";
 type RetrieveCodes$7 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
 type ListCodes$6 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+/**
+ * Narrow code set for `recordCompleted`. Mirror of `recordSubmitted`'s
+ * code surface — the SDK does NOT export `recordSubmitted` publicly
+ * (the create signing tail invokes it), but the call shape is the
+ * reference. Per ADR 9, `recordCompleted` is exposed on personal-scope
+ * `WithdrawalsClient` ONLY.
+ */
+type RecordCompletedCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "NOT_FOUND" | "NETWORK_ERROR" | "INTERNAL_ERROR";
 type WithdrawalsClient = {
     readonly create: (input: WithdrawalsCreateInput) => Promise<CapxulResult<CreateWithdrawalResult, CreateCodes$4>>;
     readonly retrieve: (withdrawalId: WithdrawalId) => Promise<CapxulResult<Withdrawal, RetrieveCodes$7>>;
     readonly list: (input?: WithdrawalsListInput) => Promise<CapxulResult<List<Withdrawal>, ListCodes$6>>;
+    /**
+     * Withdrawals v1 W4 (#467) — reconciliation pipe.
+     *
+     * Caller invokes this AFTER `withdrawals.create` resolves AND after
+     * the on-chain receipt confirms (e.g., via the harness's
+     * `chain.waitReceipt`). The mutation patches the withdrawal +
+     * execution + attempt + operation rows to terminal happy state and
+     * emits a single `operation.succeeded` outbox event joined to the
+     * original correlationId. Idempotent on already-`completed` rows.
+     *
+     * Personal-scope only — the org-scope client does NOT expose this
+     * method (mirror of `recordSubmitted`; see ADR 9 in #467).
+     */
+    readonly recordCompleted: (input: WithdrawalsRecordCompletedInput) => Promise<CapxulResult<null, RecordCompletedCodes>>;
 };
 type OrgWithdrawalsClient = {
     readonly create: (input: OrgWithdrawalsCreateInput) => Promise<CapxulResult<CreateWithdrawalResult, CreateCodes$4>>;

package/dist/{client-CXRKtbfn.d.cts → client-DW_fW9DC.d.cts}

@@ -2,7 +2,7 @@ import { Account as Account$1 } from 'viem';
 import { AnyStateMachine } from 'xstate';
 import { A as AccountId, S as SafeId, c as KycProfileId, b as ExternalAccountId, f as SubAccountId, d as OrganizationId, a as ApiKeyId, X as TimestampIso, D as DocumentId, O as OperationId, P as PaymentId, g as TransferId, k as WithdrawalId, W as WebhookEndpointId, j as WebhookEventId, M as MemberId, K as KybProfileId, V as VirtualAccountId, i as VirtualCardId } from './next-action-DkrwXYay.cjs';
 import { d as CapxulResult, C as CapxulError } from './errors-GgKrSUKp.cjs';
-import { A as Account, U as UserIdentifier, a as AccountLookupResult, S as Safe, i as KycProfile, E as ExternalAccount, L as List, v as SubAccount, B as BalanceLedgerEntry, b as ApiKey, D as Document, O as Operation, l as OperationStatus, k as Money, C as CreatePaymentResult, o as Payment, F as TransferEndpoint, f as CreateTransferResult, y as Transfer, g as CreateWithdrawalResult, _ as Withdrawal, Y as WebhookEndpoint, Z as WebhookEvent, n as Organization, J as Treasury, M as Member, K as KybProfile, V as VirtualAccount, Q as VirtualCard } from './types-DVWojoy4.cjs';
+import { A as Account, U as UserIdentifier, a as AccountLookupResult, S as Safe, i as KycProfile, E as ExternalAccount, L as List, v as SubAccount, B as BalanceLedgerEntry, b as ApiKey, D as Document, O as Operation, l as OperationStatus, k as Money, C as CreatePaymentResult, o as Payment, F as TransferEndpoint, f as CreateTransferResult, y as Transfer, g as CreateWithdrawalResult, _ as Withdrawal, Y as WebhookEndpoint, Z as WebhookEvent, n as Organization, J as Treasury, M as Member, K as KybProfile, V as VirtualAccount, Q as VirtualCard } from './types-X02RbQ2u.cjs';
 import * as types from '@repo/api-contract/gen/types';
 
 /**
@@ -282,8 +282,20 @@ type OrgDocumentsClient = {
  * Per sdk-surface.md §1a, `external_account` is a reusable withdrawal
  * destination. `create` + `list` live under the owner's nested
  * namespace (Pattern A — `accounts.externalAccounts.*` or
- * `organizations.externalAccounts.*`). `retrieve` and `remove` work by
- * ID without scoping.
+ * `organizations.externalAccounts.*`). The top-level `retrieve` and
+ * `remove` keep PERSONAL-scope semantics — for org rows route via
+ * the `organizations.externalAccounts.*` namespace which carries
+ * `organizationId` end-to-end and pins the row's owner pair to
+ * prevent cross-org IDOR (revision 1, #464).
+ *
+ * Withdrawals v1 W1 (#464) wires these stubs through the
+ * `externalAccounts/{queries,mutations}` Convex domain. The wire shape
+ * matches OpenAPI: `{ object: "external_account", id, kind, status,
+ * ..., operation: { id, status, correlationId } }` — the trust-chain
+ * ids live under the canonical nested `operation: OperationSummary`
+ * envelope (revision 3, #464), matching Withdrawal / Payment /
+ * Transfer / Organization. The SDK rebrands `id` + the nested
+ * `operation` sub-ids at the read edge.
  */
 
 type RetrieveCodes$b = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
@@ -473,35 +485,25 @@ type OrgTransfersClient = {
 
 /**
  * Withdrawals domain — funds exit Capxul via an `external_account` per
- * sdk-surface.md §1a + §4.52 + withdrawal-orchestration.mdx (slice 1
- * of Withdrawals v1, #440).
- *
- * Slice 1 NOTE — transitional input shape:
- * Until the `external_accounts` resource lands (slice 1.x or v2), the
- * destination input includes a `kind` field so the backend + SDK can
- * route to the chain_wallet rail without a real external_accounts
- * lookup. When the resource lands, `kind` becomes optional / ignored
- * and the kind is inferred from the resolved row.
+ * sdk-surface.md §1a + §4.52 + withdrawal-orchestration.mdx.
  *
- * Slice 1 NOTE — chain_wallet rail integration:
- * For evm destinations, the `externalAccountId` is treated as the
- * destination address (must start with `0x`) so the chain_wallet rail
- * can call `transferAsOwner` directly. For solana / starknet the SDK
- * accepts the create call but does NOT execute the rail submission —
- * the row stays in `processing` until external_accounts lands. The
- * caller can transition it via `markFailed` if needed.
+ * Withdrawals v1 W2 (#465) refactor:
+ * - The `kind` shim on `destination` is GONE. The backend now resolves
+ *   the destination row by FK and infers kind + rail. Anything that
+ *   doesn't route to `chain_wallet` returns `VERIFICATION_REQUIRED`.
+ * - Org-scope `create` is now a real mutation (no longer a stub).
+ *   Personal-scope keeps the on-chain submission tail; org-scope
+ *   returns the `processing` row only — Safe + Zodiac orchestration
+ *   ships in W3+ (D6).
+ * - All raw `try/catch` blocks have been replaced with `tryCatch` from
+ *   `@repo/observability`, mirroring `core/external-accounts.ts`
+ *   (precedent D2).
  */
 
 type WithdrawalsCreateInput = {
     readonly amount: Money;
     readonly destination: {
         readonly externalAccountId: ExternalAccountId;
-        /**
-         * Slice 1 transitional field. Required until the
-         * `external_accounts` resource lands; will become optional / ignored
-         * when the resource is the source of truth for kind.
-         */
-        readonly kind: "evm" | "solana" | "starknet" | "bank" | "momo" | "card_payout";
     };
     readonly source?: {
         readonly subAccountId: SubAccountId;
@@ -514,6 +516,22 @@ type WithdrawalsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
 };
+/**
+ * Withdrawals v1 W4 (#467) — input for the reconciliation pipe.
+ * Caller passes the same `txHash` that `recordSubmitted` wrote; the
+ * backend cross-checks the value against the persisted operation row.
+ *
+ * `withdrawalId` accepts either the branded `WithdrawalId` or a raw
+ * string. `txHash` is a raw string at the SDK boundary — the backend
+ * re-validates the shape via `toTxHash` at the mutation handler (the
+ * SDK package is no longer coupled to `@repo/types`'s brand surface
+ * post the alpha-epic decoupling; see
+ * `packages/sdk/docs/internal/decoupling-prep.md`).
+ */
+type WithdrawalsRecordCompletedInput = {
+    readonly withdrawalId: WithdrawalId | string;
+    readonly txHash: string;
+};
 type OrgWithdrawalsCreateInput = WithdrawalsCreateInput & {
     readonly organizationId: OrganizationId;
 };
@@ -526,13 +544,35 @@ type OrgWithdrawalsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
 };
-type CreateCodes$4 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "INSUFFICIENT_BALANCE" | "IDEMPOTENCY_CONFLICT" | "KYC_REQUIRED" | "POLICY_DENIED" | "RATE_LIMITED" | "NETWORK_ERROR";
+type CreateCodes$4 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "INSUFFICIENT_BALANCE" | "IDEMPOTENCY_CONFLICT" | "KYC_REQUIRED" | "POLICY_DENIED" | "RATE_LIMITED" | "NETWORK_ERROR" | "NOT_FOUND" | "VERIFICATION_REQUIRED";
 type RetrieveCodes$7 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
 type ListCodes$6 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+/**
+ * Narrow code set for `recordCompleted`. Mirror of `recordSubmitted`'s
+ * code surface — the SDK does NOT export `recordSubmitted` publicly
+ * (the create signing tail invokes it), but the call shape is the
+ * reference. Per ADR 9, `recordCompleted` is exposed on personal-scope
+ * `WithdrawalsClient` ONLY.
+ */
+type RecordCompletedCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "NOT_FOUND" | "NETWORK_ERROR" | "INTERNAL_ERROR";
 type WithdrawalsClient = {
     readonly create: (input: WithdrawalsCreateInput) => Promise<CapxulResult<CreateWithdrawalResult, CreateCodes$4>>;
     readonly retrieve: (withdrawalId: WithdrawalId) => Promise<CapxulResult<Withdrawal, RetrieveCodes$7>>;
     readonly list: (input?: WithdrawalsListInput) => Promise<CapxulResult<List<Withdrawal>, ListCodes$6>>;
+    /**
+     * Withdrawals v1 W4 (#467) — reconciliation pipe.
+     *
+     * Caller invokes this AFTER `withdrawals.create` resolves AND after
+     * the on-chain receipt confirms (e.g., via the harness's
+     * `chain.waitReceipt`). The mutation patches the withdrawal +
+     * execution + attempt + operation rows to terminal happy state and
+     * emits a single `operation.succeeded` outbox event joined to the
+     * original correlationId. Idempotent on already-`completed` rows.
+     *
+     * Personal-scope only — the org-scope client does NOT expose this
+     * method (mirror of `recordSubmitted`; see ADR 9 in #467).
+     */
+    readonly recordCompleted: (input: WithdrawalsRecordCompletedInput) => Promise<CapxulResult<null, RecordCompletedCodes>>;
 };
 type OrgWithdrawalsClient = {
     readonly create: (input: OrgWithdrawalsCreateInput) => Promise<CapxulResult<CreateWithdrawalResult, CreateCodes$4>>;