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

package/dist/index.js

@@ -71,9 +71,79 @@ function fromConvexError(error) {
 // src/core/accounts.ts
 function createAccountsClient(config = {}) {
   return {
-    retrieve: async () => stub("accounts.retrieve"),
+    retrieve: async (accountId) => {
+      if (!config.data) {
+        return stub("accounts.retrieve");
+      }
+      try {
+        const account = await config.data.query(
+          api.openfort.queries.getMyAccount,
+          {}
+        );
+        if (account.id !== accountId) {
+          return [
+            new CapxulError({
+              code: "PERMISSION_DENIED",
+              message: "accounts.retrieve currently supports the authenticated caller's own account only.",
+              details: {
+                requestedAccountId: accountId,
+                authenticatedAccountId: account.id
+              }
+            }),
+            null
+          ];
+        }
+        return [null, account];
+      } catch (cause) {
+        return [fromConvexError(cause), null];
+      }
+    },
     lookup: async () => stub("accounts.lookup"),
-    update: async () => stub("accounts.update"),
+    update: async (input) => {
+      if (!config.data) {
+        return stub("accounts.update");
+      }
+      if (input.countryCode !== void 0) {
+        return [
+          new CapxulError({
+            code: "INVALID_INPUT",
+            message: "accounts.update does not support countryCode yet \u2014 backend mutation only patches displayName and username.",
+            details: { field: "countryCode" }
+          }),
+          null
+        ];
+      }
+      try {
+        const current = await config.data.query(
+          api.openfort.queries.getMyAccount,
+          {}
+        );
+        if (current.id !== input.accountId) {
+          return [
+            new CapxulError({
+              code: "PERMISSION_DENIED",
+              message: "accounts.update currently supports the authenticated caller's own account only.",
+              details: {
+                requestedAccountId: input.accountId,
+                authenticatedAccountId: current.id
+              }
+            }),
+            null
+          ];
+        }
+        await config.data.mutation(api.openfort.mutations.updateProfile, {
+          displayName: input.name,
+          username: input.username
+        });
+        const updated = await config.data.query(
+          api.openfort.queries.getMyAccount,
+          {}
+        );
+        return [null, updated];
+      } catch (cause) {
+        return [fromConvexError(cause), null];
+      }
+    },
     provisionPersonal: async (input) => {
       if (!config.data) {
         return stub(
@@ -697,7 +767,34 @@ function createMeClient(config = {}) {
         return [fromConvexError(cause), null];
       }
     },
-    update: async () => stub("me.update")
+    update: async (input) => {
+      if (!config.data) {
+        return stub("me.update");
+      }
+      if (input.countryCode !== void 0) {
+        return [
+          new CapxulError({
+            code: "INVALID_INPUT",
+            message: "me.update does not support countryCode yet \u2014 backend mutation only patches displayName and username.",
+            details: { field: "countryCode" }
+          }),
+          null
+        ];
+      }
+      try {
+        await config.data.mutation(api.openfort.mutations.updateProfile, {
+          displayName: input.name,
+          username: input.username
+        });
+        const account = await config.data.query(
+          api.openfort.queries.getMyAccount,
+          {}
+        );
+        return [null, account];
+      } catch (cause) {
+        return [fromConvexError(cause), null];
+      }
+    }
   };
 }
 
@@ -1100,24 +1197,298 @@ function createOrgTransfersClient() {
     cancel: async () => stub("organizations.transfers.cancel")
   };
 }
-
-// src/core/withdrawals.ts
-function createWithdrawalsClient() {
+var EVM_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+function createWithdrawalsClient(config = {}) {
   return {
-    create: async () => stub("withdrawals.create"),
-    retrieve: async () => stub("withdrawals.retrieve"),
-    list: async () => stub("withdrawals.list")
+    create: async (input) => {
+      if (!config.data) {
+        return stub("withdrawals.create");
+      }
+      let created = null;
+      let submitted = null;
+      try {
+        created = await config.data.mutation(
+          api.withdrawals.mutations.create,
+          {
+            amount: input.amount,
+            destination: {
+              externalAccountId: input.destination.externalAccountId,
+              kind: input.destination.kind
+            },
+            source: input.source,
+            reference: input.reference,
+            idempotencyKey: input.idempotencyKey
+          }
+        );
+        if (!created) {
+          return [
+            new CapxulError({
+              code: "NETWORK_ERROR",
+              message: "withdrawals.create returned no withdrawal resource"
+            }),
+            null
+          ];
+        }
+        if (created.status !== "processing" || created.operation.status !== "processing") {
+          return [null, created];
+        }
+        if (input.destination.kind !== "evm") {
+          return [null, created];
+        }
+        if (!config.signer || !config.signing) {
+          return [null, created];
+        }
+        if (!EVM_ADDRESS_RE.test(input.destination.externalAccountId)) {
+          throw new CapxulError({
+            code: "INVALID_INPUT",
+            message: "destination.externalAccountId must be a 0x-prefixed EVM address while external_accounts resolution is pending (slice 1).",
+            details: { field: "destination.externalAccountId" }
+          });
+        }
+        const currentSigner = await config.data.query(
+          api.safe.queries.getMySignerAddress,
+          {}
+        );
+        if (!currentSigner?.address) {
+          throw new CapxulError({
+            code: "PERMISSION_DENIED",
+            message: "No signer is registered for the authenticated account.",
+            details: { withdrawalId: created.id }
+          });
+        }
+        if (getAddress(currentSigner.address) !== getAddress(config.signer.address)) {
+          throw new CapxulError({
+            code: "PERMISSION_DENIED",
+            message: "Configured signer does not match the authenticated account signer.",
+            details: {
+              withdrawalId: created.id,
+              expectedSignerAddress: currentSigner.address,
+              actualSignerAddress: config.signer.address
+            }
+          });
+        }
+        const submission = await config.data.query(
+          api.withdrawals.queries.prepareSubmission,
+          { withdrawalId: created.id }
+        );
+        if (!submission?.externalAccountId) {
+          throw new CapxulError({
+            code: "NETWORK_ERROR",
+            message: "withdrawals.prepareSubmission returned no destination.",
+            details: { withdrawalId: created.id }
+          });
+        }
+        const transfer = await transferAsOwner(
+          {
+            signer: config.signer,
+            signing: config.signing
+          },
+          {
+            tokenAddress: resolvePaymentTokenAddress(submission.amount.currency),
+            recipientAddress: submission.externalAccountId,
+            amount: toTokenUnits(submission.amount.value, 6)
+          }
+        );
+        if (!transfer.success) {
+          throw new CapxulError({
+            code: "NETWORK_ERROR",
+            message: "Bundler submission did not succeed.",
+            details: {
+              withdrawalId: created.id,
+              txHash: transfer.txHash,
+              userOpHash: transfer.userOpHash
+            }
+          });
+        }
+        submitted = {
+          txHash: transfer.txHash,
+          userOpHash: transfer.userOpHash
+        };
+        await config.data.mutation(
+          api.withdrawals.mutations.recordSubmitted,
+          {
+            withdrawalId: created.id,
+            txHash: transfer.txHash,
+            userOpHash: transfer.userOpHash
+          }
+        );
+        return [null, created];
+      } catch (cause) {
+        const error = mapCreateError2(fromConvexError(cause));
+        if (created?.id && created.status === "processing" && !submitted) {
+          await bestEffortMarkFailed2({ data: config.data }, created.id, error);
+        }
+        if (submitted && created?.id) {
+          return [
+            new CapxulError({
+              code: "NETWORK_ERROR",
+              message: "Withdrawal was submitted on-chain, but backend submission tracking failed.",
+              cause,
+              details: {
+                withdrawalId: created.id,
+                txHash: submitted.txHash,
+                userOpHash: submitted.userOpHash
+              }
+            }),
+            null
+          ];
+        }
+        return [error, null];
+      }
+    },
+    retrieve: async (withdrawalId) => {
+      if (!config.data) {
+        return stub("withdrawals.retrieve");
+      }
+      try {
+        const withdrawal = await config.data.query(
+          api.withdrawals.queries.retrieve,
+          { withdrawalId }
+        );
+        if (!withdrawal) {
+          return [
+            new CapxulError({
+              code: "NOT_FOUND",
+              message: `withdrawal ${withdrawalId} not found`
+            }),
+            null
+          ];
+        }
+        return [null, withdrawal];
+      } catch (cause) {
+        return [
+          fromConvexError(cause),
+          null
+        ];
+      }
+    },
+    list: async (input) => {
+      if (!config.data) {
+        return stub("withdrawals.list");
+      }
+      try {
+        const result = await config.data.query(
+          api.withdrawals.queries.list,
+          {
+            limit: input?.limit,
+            cursor: input?.cursor
+          }
+        );
+        return [null, result];
+      } catch (cause) {
+        return [
+          fromConvexError(cause),
+          null
+        ];
+      }
+    }
   };
 }
-function createOrgWithdrawalsClient() {
+function createOrgWithdrawalsClient(config = {}) {
   return {
+    // Slice 1 ships personal-scope only end-to-end; org-scope create
+    // remains stubbed pending org-scoped backend mutation. List + retrieve
+    // are wired through the org-aware query.
     create: async () => stub(
       "organizations.withdrawals.create"
     ),
-    retrieve: async () => stub("organizations.withdrawals.retrieve"),
-    list: async () => stub("organizations.withdrawals.list")
+    retrieve: async (input) => {
+      if (!config.data) {
+        return stub(
+          "organizations.withdrawals.retrieve"
+        );
+      }
+      try {
+        const withdrawal = await config.data.query(
+          api.withdrawals.queries.retrieve,
+          { withdrawalId: input.withdrawalId }
+        );
+        if (!withdrawal) {
+          return [
+            new CapxulError({
+              code: "NOT_FOUND",
+              message: `withdrawal ${input.withdrawalId} not found`
+            }),
+            null
+          ];
+        }
+        const ownerCheck = withdrawal.owner;
+        if (ownerCheck?.type !== "organization" || ownerCheck.id !== input.organizationId) {
+          return [
+            new CapxulError({
+              code: "NOT_FOUND",
+              message: `withdrawal ${input.withdrawalId} does not belong to organization ${input.organizationId}`
+            }),
+            null
+          ];
+        }
+        return [null, withdrawal];
+      } catch (cause) {
+        return [
+          fromConvexError(cause),
+          null
+        ];
+      }
+    },
+    list: async (input) => {
+      if (!config.data) {
+        return stub(
+          "organizations.withdrawals.list"
+        );
+      }
+      try {
+        const result = await config.data.query(
+          api.withdrawals.queries.listOrg,
+          {
+            organizationId: input.organizationId,
+            limit: input.limit,
+            cursor: input.cursor
+          }
+        );
+        return [null, result];
+      } catch (cause) {
+        return [
+          fromConvexError(cause),
+          null
+        ];
+      }
+    }
   };
 }
+async function bestEffortMarkFailed2(config, withdrawalId, error) {
+  try {
+    await config.data.mutation(api.withdrawals.mutations.markFailed, {
+      withdrawalId,
+      errorCode: error.code,
+      errorMessage: error.message
+    });
+  } catch {
+  }
+}
+function mapCreateError2(error) {
+  switch (error.code) {
+    case "NOT_AUTHENTICATED":
+    case "PERMISSION_DENIED":
+    case "INVALID_INPUT":
+    case "INSUFFICIENT_BALANCE":
+    case "IDEMPOTENCY_CONFLICT":
+    case "KYC_REQUIRED":
+    case "POLICY_DENIED":
+    case "RATE_LIMITED":
+    case "NETWORK_ERROR":
+      return error;
+    default:
+      return new CapxulError({
+        code: "NETWORK_ERROR",
+        message: error.message,
+        cause: error,
+        details: error.details,
+        operationId: error.operationId,
+        correlationId: error.correlationId,
+        retryable: error.retryable
+      });
+  }
+}
 
 // src/core/webhook-endpoints.ts
 function createWebhookEndpointsClient() {
@@ -1217,7 +1588,7 @@ function createOrganizationsClient(config = {}) {
     },
     payments: createOrgPaymentsClient(),
     transfers: createOrgTransfersClient(),
-    withdrawals: createOrgWithdrawalsClient(),
+    withdrawals: createOrgWithdrawalsClient(config),
     documents: createOrgDocumentsClient(),
     webhookEndpoints: createWebhookEndpointsClient(),
     webhookEvents: createWebhookEventsClient()
@@ -1232,6 +1603,96 @@ function createSubAccountsClient() {
   };
 }
 
+// src/core/token-transfers.ts
+var toTokenTransferId = (raw) => {
+  if (typeof raw !== "string" || raw.length === 0) {
+    throw new Error(
+      `Invalid tokenTransferId: expected non-empty string, got ${String(raw)}`
+    );
+  }
+  return raw;
+};
+function brandRow(row) {
+  return {
+    ...row,
+    id: toTokenTransferId(row.id)
+  };
+}
+function createTokenTransfersClient(config = {}) {
+  return {
+    list: async (input) => {
+      if (!config.data) {
+        return stub("tokenTransfers.list");
+      }
+      try {
+        const raw = await config.data.query(
+          api.tokenTransfers.queries.list,
+          {
+            limit: input?.limit,
+            cursor: input?.cursor,
+            direction: input?.direction
+          }
+        );
+        if (!raw) {
+          return [
+            new CapxulError({
+              code: "NOT_AUTHENTICATED",
+              message: "tokenTransfers.list requires an authenticated session."
+            }),
+            null
+          ];
+        }
+        return [
+          null,
+          {
+            object: "list",
+            data: raw.items.map(brandRow),
+            page: {
+              hasMore: raw.hasMore,
+              nextCursor: raw.nextCursor
+            },
+            displayCurrency: raw.displayCurrency
+          }
+        ];
+      } catch (cause) {
+        return [fromConvexError(cause), null];
+      }
+    },
+    retrieve: async (input) => {
+      if (!config.data) {
+        return stub("tokenTransfers.retrieve");
+      }
+      try {
+        const raw = await config.data.query(
+          api.tokenTransfers.queries.getByTxLogIndex,
+          {
+            txHash: input.txHash,
+            logIndex: input.logIndex,
+            chainId: input.chainId
+          }
+        );
+        if (!raw) {
+          return [
+            new CapxulError({
+              code: "NOT_FOUND",
+              message: `tokenTransfer (txHash=${input.txHash}, logIndex=${input.logIndex}) not found or not visible to caller.`,
+              details: {
+                txHash: input.txHash,
+                logIndex: input.logIndex,
+                chainId: input.chainId
+              }
+            }),
+            null
+          ];
+        }
+        return [null, brandRow(raw)];
+      } catch (cause) {
+        return [fromConvexError(cause), null];
+      }
+    }
+  };
+}
+
 // src/core/virtual-accounts.ts
 function createVirtualAccountsClient() {
   return {
@@ -2083,7 +2544,8 @@ function createCapxulClient(config = {}) {
     organizations: createOrganizationsClient(config),
     payments: createPaymentsClient(config),
     transfers: createTransfersClient(),
-    withdrawals: createWithdrawalsClient(),
+    tokenTransfers: createTokenTransfersClient(config),
+    withdrawals: createWithdrawalsClient(config),
     documents: createDocumentsClient(),
     subAccounts: createSubAccountsClient(),
     virtualAccounts: createVirtualAccountsClient(),
@@ -2201,4 +2663,4 @@ function isWebhookEvent(value) {
   return typeof candidate.id === "string" && typeof candidate.type === "string" && typeof candidate.createdAt === "string" && (candidate.operationId === void 0 || typeof candidate.operationId === "string") && (candidate.correlationId === void 0 || typeof candidate.correlationId === "string") && !!candidate.data && typeof candidate.data === "object" && !Array.isArray(candidate.data);
 }
 
-export { CapxulError, createAuthFlowMachine, createCapxulClient, createLocalSigner, createOnboardingFlowMachine, createProvisioningMachine as createProvisioningFlowMachine, makeHttpTransport, matchAction, matchError, matchStatus, toAccountId, toApiKeyId, toBalanceLedgerEntryId, toDocumentId, toEmail, toExternalAccountId, toKybProfileId, toKycProfileId, toMemberId, toOperationId, toOrganizationId, toPaymentId, toPhoneNumber, toSafeId, toSubAccountId, toTransferId, toTreasuryId, toUsername, toVirtualAccountId, toVirtualCardId, toWebhookEndpointId, toWebhookEventId, toWithdrawalId, tryCatch, verifyWebhook };
+export { CapxulError, createAuthFlowMachine, createCapxulClient, createLocalSigner, createOnboardingFlowMachine, createProvisioningMachine as createProvisioningFlowMachine, makeHttpTransport, matchAction, matchError, matchStatus, toAccountId, toApiKeyId, toBalanceLedgerEntryId, toDocumentId, toEmail, toExternalAccountId, toKybProfileId, toKycProfileId, toMemberId, toOperationId, toOrganizationId, toPaymentId, toPhoneNumber, toSafeId, toSubAccountId, toTokenTransferId, toTransferId, toTreasuryId, toUsername, toVirtualAccountId, toVirtualCardId, toWebhookEndpointId, toWebhookEventId, toWithdrawalId, tryCatch, verifyWebhook };

package/dist/{types-BE3tVIOI.d.ts → types-75UokagF.d.ts}

@@ -155,7 +155,15 @@ type Payment = WithStatus<WirePaymentWithBrand, PaymentStatus>;
 type CreatePaymentResult = WithStatus<WirePaymentWithBrand, "processing" | "action_required" | "failed">;
 type PaymentParty = types.PaymentParty;
 type WireWithdrawalWithBrand = Rebrand<types.Withdrawal, WithdrawalId>;
-type WithdrawalStatus = PaymentStatus;
+/**
+ * Canon-aligned superset (resources.mdx §withdrawal lifecycle note).
+ * Wider than `OperationStatus` because `submitted → completed` is a
+ * withdrawal-specific transition driven by external reconciliation
+ * the operation envelope cannot witness directly. Slice 1 of
+ * Withdrawals v1 (#440) widened this from `PaymentStatus` to match
+ * canon.
+ */
+type WithdrawalStatus = "draft" | "action_required" | "processing" | "submitted" | "completed" | "failed" | "canceled";
 type Withdrawal = WithStatus<WireWithdrawalWithBrand, WithdrawalStatus>;
 type CreateWithdrawalResult = WithStatus<WireWithdrawalWithBrand, "processing" | "action_required" | "failed">;
 type WireTransferWithBrand = Rebrand<types.Transfer, TransferId>;

package/dist/{types-z4VLz9rS.d.cts → types-DVWojoy4.d.cts}

@@ -155,7 +155,15 @@ type Payment = WithStatus<WirePaymentWithBrand, PaymentStatus>;
 type CreatePaymentResult = WithStatus<WirePaymentWithBrand, "processing" | "action_required" | "failed">;
 type PaymentParty = types.PaymentParty;
 type WireWithdrawalWithBrand = Rebrand<types.Withdrawal, WithdrawalId>;
-type WithdrawalStatus = PaymentStatus;
+/**
+ * Canon-aligned superset (resources.mdx §withdrawal lifecycle note).
+ * Wider than `OperationStatus` because `submitted → completed` is a
+ * withdrawal-specific transition driven by external reconciliation
+ * the operation envelope cannot witness directly. Slice 1 of
+ * Withdrawals v1 (#440) widened this from `PaymentStatus` to match
+ * canon.
+ */
+type WithdrawalStatus = "draft" | "action_required" | "processing" | "submitted" | "completed" | "failed" | "canceled";
 type Withdrawal = WithStatus<WireWithdrawalWithBrand, WithdrawalStatus>;
 type CreateWithdrawalResult = WithStatus<WireWithdrawalWithBrand, "processing" | "action_required" | "failed">;
 type WireTransferWithBrand = Rebrand<types.Transfer, TransferId>;

package/dist/webhooks.d.cts

@@ -1,4 +1,4 @@
-import { Z as WebhookEvent } from './types-z4VLz9rS.cjs';
+import { Z as WebhookEvent } from './types-DVWojoy4.cjs';
 import '@repo/api-contract/gen/types';
 import './next-action-DkrwXYay.cjs';
 

package/dist/webhooks.d.ts

@@ -1,4 +1,4 @@
-import { Z as WebhookEvent } from './types-BE3tVIOI.js';
+import { Z as WebhookEvent } from './types-75UokagF.js';
 import '@repo/api-contract/gen/types';
 import './next-action-DkrwXYay.js';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capxul/sdk",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "description": "Headless TypeScript client for Capxul's /v1/* HTTP contract.",
   "license": "UNLICENSED",
   "private": false,
@@ -71,8 +71,8 @@
     "vitest": "^4.1.2",
     "zod": "^4.3.6",
     "@repo/api-contract": "0.0.0",
-    "@repo/config": "0.0.0",
     "@repo/backend": "0.0.0",
+    "@repo/config": "0.0.0",
     "@repo/observability": "0.0.0",
     "@repo/platform-kernel": "0.0.0",
     "@repo/typescript-config": "0.0.0"