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

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @capxul/sdk
 
+## 0.1.0-alpha.8
+
+### 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.4
 
 ### Minor Changes

package/README.md

@@ -19,9 +19,9 @@ pnpm add @capxul/sdk @capxul/sdk-react
 React-flavored entry point lives in `@capxul/sdk-react`. Pick:
 
 - **Browser apps (recommended).** Install both. Use
-  `<CapxulProvider publishableKey="cap_pk_…">` from `@capxul/sdk-react`
-  and the `useMe` / `useCapxulStatus` hooks. See that package's
-  README for the lazy-DX example.
+  `<CapxulProvider config={{ mode: "publishable-key", publishableKey }}>`
+  from `@capxul/sdk-react` and the `useMe` / `useCapxulStatus` hooks.
+  See that package's README for the lazy-DX example.
 - **Server / CLI / scripts.** Install only `@capxul/sdk`. Build a
   `CapxulClient` directly with your own auth and Convex adapters
   (see "Server-side construction" below).
@@ -76,11 +76,93 @@ runtime URLs lazily — no need to ship secrets to the client:
 ```tsx
 import { CapxulProvider, useMe, useCapxulStatus } from "@capxul/sdk-react";
 
-<CapxulProvider publishableKey="cap_pk_live_…">
+<CapxulProvider
+  config={{
+    mode: "publishable-key",
+    publishableKey: process.env.NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY!,
+  }}
+>
   <App />
 </CapxulProvider>;
 ```
 
+## Publishable-key transport
+
+The browser transport accepts a publishable key, then lazily resolves
+runtime URLs by POSTing to `/v1/client/bootstrap` on the first auth or
+`ensureRuntime()` call. The successful backend response is intentionally
+small:
+
+```json
+{ "authBaseUrl": "https://<deployment>.convex.site/api/auth", "convexUrl": "https://<deployment>.convex.cloud" }
+```
+
+The resolved runtime is cached for the lifetime of the transport. Concurrent
+callers share one bootstrap request, successful resolutions are reused, and
+failed bootstrap attempts reset so the next call can retry. Tests and
+non-default deployments can inject both `fetchImpl` and an absolute
+`bootstrapUrl`:
+
+```ts
+import { makeHttpTransport, CapxulError } from "@capxul/sdk";
+
+const transport = makeHttpTransport({
+  mode: "publishable-key",
+  publishableKey: process.env.NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY!,
+  bootstrapUrl: "https://api.capxul.com/v1/client/bootstrap",
+  fetchImpl: fetch,
+});
+
+await transport.ensureRuntime();
+```
+
+Local setup errors and backend bootstrap errors both use `CapxulError`, but
+carry different `details.source` values:
+
+```ts
+try {
+  await transport.ensureRuntime();
+} catch (error) {
+  if (error instanceof CapxulError) {
+    if (error.details?.source === "sdk-config") {
+      // Missing or malformed local config, such as publishableKey or bootstrapUrl.
+    }
+    if (error.details?.source === "backend-bootstrap") {
+      // Sanitized backend refusal, such as NOT_AUTHENTICATED or PERMISSION_DENIED.
+    }
+  }
+}
+```
+
+Runtime proof status:
+
+| Surface | Source support | Runtime proof | Status |
+|---|---|---|---|
+| SDK transport | `makeHttpTransport({ mode: "publishable-key", publishableKey })` | `packages/sdk/tests/unit/transport.test.ts` proves config validation, singleflight bootstrap, retry after failure, lifecycle transitions, and sanitized backend errors. | Proven with mocked fetch |
+| React provider | `CapxulProvider config={{ mode: "publishable-key", ... }}` | `packages/sdk-react/ops/proof/react-headless.test.tsx` proves bootstrap before a real `useMe()` read through the provider and lazy Convex data client. | Proven with mocked fetch + headless React |
+| Reference CLI | `bootstrap probe --mock --json` | `apps/reference-cli/scripts/agent-driver.ts` phase 0 and the direct CLI command prove provider/bootstrap/auth ordering and sanitized output. | Proven locally; live endpoint remains manual-key gated |
+
+Copy-paste local replication:
+
+```bash
+corepack pnpm --filter @capxul/sdk check-types
+corepack pnpm --filter @capxul/sdk build
+corepack pnpm --filter @capxul/sdk-react check-types
+corepack pnpm --filter @capxul/sdk-react build
+corepack pnpm --filter @capxul/reference-cli check-types
+corepack pnpm --filter @capxul/reference-cli build
+node apps/reference-cli/dist/cli.js bootstrap probe --mock --json
+```
+
+Run the SDK and React SDK builds before the reference CLI typecheck in a
+fresh checkout; the CLI depends on their generated declaration outputs.
+
+Expected sanitized pass signal:
+
+```json
+{"command":"bootstrap.probe","ok":true,"mode":"publishable-key","status":"ready","bootstrapRequests":1,"authRequests":1,"keyLengthClass":"provided","mocked":true}
+```
+
 ## Public surface (alpha)
 
 ```ts
@@ -90,7 +172,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-ByzDfG98.d.ts}

@@ -2,8 +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 * as types from '@repo/api-contract/gen/types';
+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, a0 as CreateApiKeyRequest, a1 as CreateDocumentRequest, 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, a2 as CreateWebhookEndpointRequest, Y as WebhookEndpoint, Z as WebhookEvent, n as Organization, J as Treasury, M as Member, K as KybProfile, a3 as CreateVirtualAccountRequest, V as VirtualAccount, a4 as CreateVirtualCardRequest, Q as VirtualCard } from './types-PM4AQRLP.js';
 
 /**
  * Accounts domain — individual user accounts per sdk-surface.md §1a.
@@ -111,7 +110,7 @@ type AccountsClient = {
  * on `create` only; subsequent reads omit it.
  */
 
-type ApiKeysCreateInput = types.CreateApiKeyRequest & {
+type ApiKeysCreateInput = CreateApiKeyRequest & {
     readonly organizationId: OrganizationId;
 };
 type ApiKeysRetrieveInput = {
@@ -236,7 +235,7 @@ type AuthClient = {
  * bank_statement | tax_form`.
  */
 
-type DocumentsCreateInput = types.CreateDocumentRequest;
+type DocumentsCreateInput = CreateDocumentRequest;
 type DocumentsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
@@ -282,8 +281,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 +484,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 +515,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 +543,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>>;
@@ -549,7 +588,7 @@ type OrgWithdrawalsClient = {
  * variant at call time and require `organizationId` explicitly.
  */
 
-type WebhookEndpointsCreateInput = types.CreateWebhookEndpointRequest & {
+type WebhookEndpointsCreateInput = CreateWebhookEndpointRequest & {
     readonly organizationId: OrganizationId;
 };
 type WebhookEndpointsRetrieveInput = {
@@ -871,6 +910,7 @@ type TransportRuntime = {
  */
 type HttpTransport = {
     readonly fetch: (path: string, init?: RequestInit) => Promise<Response>;
+    readonly ensureRuntime: () => Promise<TransportRuntime>;
     readonly authBaseUrl: string;
     readonly convexUrl: string;
     readonly getState: () => TransportState;
@@ -884,8 +924,11 @@ type HttpTransport = {
 /**
  * Build an `HttpTransport` from a `BrowserCapxulConfig`.
  *
- * Throws `Errors.invalidInput("authBaseUrl" | "convexUrl", reason)`
- * when the build-time-urls variant is missing required URLs.
+ * Throws `CapxulError<"INVALID_INPUT">` with
+ * `details.source === "sdk-config"` when local transport config is
+ * malformed. Backend bootstrap failures also throw `CapxulError`, but
+ * carry `details.source === "backend-bootstrap"` so consumers can
+ * distinguish setup mistakes from server-side bootstrap refusals.
  */
 declare function makeHttpTransport(config: BrowserCapxulConfig): HttpTransport;
 
@@ -1015,7 +1058,7 @@ type TokenTransfersClient = {
  * in the create payload rather than nesting the route under the owner.
  */
 
-type VirtualAccountsCreateInput = types.CreateVirtualAccountRequest;
+type VirtualAccountsCreateInput = CreateVirtualAccountRequest;
 type VirtualAccountsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
@@ -1040,7 +1083,7 @@ type VirtualAccountsClient = {
  * Uses Pattern C (ownerKind in body).
  */
 
-type VirtualCardsCreateInput = types.CreateVirtualCardRequest;
+type VirtualCardsCreateInput = CreateVirtualCardRequest;
 type VirtualCardsListInput = {
     readonly limit?: number;
     readonly cursor?: string;

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

@@ -2,8 +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 * as types from '@repo/api-contract/gen/types';
+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, a0 as CreateApiKeyRequest, a1 as CreateDocumentRequest, 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, a2 as CreateWebhookEndpointRequest, Y as WebhookEndpoint, Z as WebhookEvent, n as Organization, J as Treasury, M as Member, K as KybProfile, a3 as CreateVirtualAccountRequest, V as VirtualAccount, a4 as CreateVirtualCardRequest, Q as VirtualCard } from './types-hfcOE7Oi.cjs';
 
 /**
  * Accounts domain — individual user accounts per sdk-surface.md §1a.
@@ -111,7 +110,7 @@ type AccountsClient = {
  * on `create` only; subsequent reads omit it.
  */
 
-type ApiKeysCreateInput = types.CreateApiKeyRequest & {
+type ApiKeysCreateInput = CreateApiKeyRequest & {
     readonly organizationId: OrganizationId;
 };
 type ApiKeysRetrieveInput = {
@@ -236,7 +235,7 @@ type AuthClient = {
  * bank_statement | tax_form`.
  */
 
-type DocumentsCreateInput = types.CreateDocumentRequest;
+type DocumentsCreateInput = CreateDocumentRequest;
 type DocumentsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
@@ -282,8 +281,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 +484,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 +515,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 +543,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>>;
@@ -549,7 +588,7 @@ type OrgWithdrawalsClient = {
  * variant at call time and require `organizationId` explicitly.
  */
 
-type WebhookEndpointsCreateInput = types.CreateWebhookEndpointRequest & {
+type WebhookEndpointsCreateInput = CreateWebhookEndpointRequest & {
     readonly organizationId: OrganizationId;
 };
 type WebhookEndpointsRetrieveInput = {
@@ -871,6 +910,7 @@ type TransportRuntime = {
  */
 type HttpTransport = {
     readonly fetch: (path: string, init?: RequestInit) => Promise<Response>;
+    readonly ensureRuntime: () => Promise<TransportRuntime>;
     readonly authBaseUrl: string;
     readonly convexUrl: string;
     readonly getState: () => TransportState;
@@ -884,8 +924,11 @@ type HttpTransport = {
 /**
  * Build an `HttpTransport` from a `BrowserCapxulConfig`.
  *
- * Throws `Errors.invalidInput("authBaseUrl" | "convexUrl", reason)`
- * when the build-time-urls variant is missing required URLs.
+ * Throws `CapxulError<"INVALID_INPUT">` with
+ * `details.source === "sdk-config"` when local transport config is
+ * malformed. Backend bootstrap failures also throw `CapxulError`, but
+ * carry `details.source === "backend-bootstrap"` so consumers can
+ * distinguish setup mistakes from server-side bootstrap refusals.
  */
 declare function makeHttpTransport(config: BrowserCapxulConfig): HttpTransport;
 
@@ -1015,7 +1058,7 @@ type TokenTransfersClient = {
  * in the create payload rather than nesting the route under the owner.
  */
 
-type VirtualAccountsCreateInput = types.CreateVirtualAccountRequest;
+type VirtualAccountsCreateInput = CreateVirtualAccountRequest;
 type VirtualAccountsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
@@ -1040,7 +1083,7 @@ type VirtualAccountsClient = {
  * Uses Pattern C (ownerKind in body).
  */
 
-type VirtualCardsCreateInput = types.CreateVirtualCardRequest;
+type VirtualCardsCreateInput = CreateVirtualCardRequest;
 type VirtualCardsListInput = {
     readonly limit?: number;
     readonly cursor?: string;