@universal-everything/sdk-core 1.0.0-dev.cb4e80f

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2023 LUKSO Blockchain GmbH
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,98 @@
+# @universal-everything/sdk-core
+
+Framework-agnostic TypeScript client for the universal-relayer API.
+Zero runtime deps — uses the `fetch` global and native types.
+
+Every framework adapter (`sdk-react`, `sdk-vue`, `sdk-svelte`) and the
+`@universal-everything/ui` web components build on top of this. Use it
+directly from Node, Deno, Bun, Cloudflare Workers, or vanilla browser
+JS.
+
+## Install
+
+```bash
+pnpm add @universal-everything/sdk-core
+```
+
+## Quick start
+
+```ts
+import { WalletKitClient, WalletKitError } from "@universal-everything/sdk-core";
+
+const client = new WalletKitClient({
+  baseUrl: "https://relayer.example.com",
+  getAccessToken: async () => "your-privy-access-token",
+});
+
+try {
+  const wallets = await client.listWallets();
+  console.log(wallets);
+} catch (err) {
+  if (err instanceof WalletKitError && err.code === "unauthenticated") {
+    // refresh token + retry
+  } else {
+    throw err;
+  }
+}
+```
+
+## What's in the box
+
+- `WalletKitClient` — one class, every endpoint.
+  - `me()`, `listWallets()`, `getWallet(id)`, `createWallet()`,
+    `patchWallet()`, `deleteWallet()`
+  - `listProfiles()`, `getProfile(id)`, `deployProfile()`, `importProfile()`
+  - `signTransaction()`, `signMessage()`, `signLsp25()`, `relaySponsored()`
+  - `getQuota()`, `beginKeyImport()` / `completeKeyImport()`,
+    `requestKeyExport()` / `cancelKeyExport()` / `completeKeyExport()`
+- `WalletKitError` — every non-2xx response throws this with:
+  - `status: number` — HTTP status
+  - `code: string` — server's `error` discriminator (e.g.
+    `insufficient_quota`, `profile_not_found`, `unauthenticated`).
+    Network failures surface as `code: "network_error"`.
+  - `body: unknown` — parsed response body, useful for rich errors like
+    `{ error: "insufficient_quota", requested, available }`.
+- Provider interfaces — `IdentityProvider`, `KeyCustodyProvider`, and
+  their error types. Implemented by `sdk-core-privy` (production) and
+  `sdk-core-local` (tests / local dev).
+
+## Authorization
+
+- **Session auth**: pass `getAccessToken` to the constructor. Called
+  before each request. Return `null` if no session; the client omits
+  the `Authorization` header.
+- **Privy per-op auth** (for operations on user-owned Privy wallets):
+  pass an `opContext` per call. `signMessage`, `signTransaction`,
+  `signLsp25`, `relaySponsored` all accept one in their options:
+  ```ts
+  await client.signMessage(msg, {
+    opContext: {
+      authorizationSignature: "…",
+      requestExpiry: Date.now() + 60_000,
+    },
+  });
+  ```
+
+## Custom fetch
+
+Pass `fetch` in the constructor if you need to wire retries, proxying,
+or a test mock:
+
+```ts
+const client = new WalletKitClient({
+  baseUrl,
+  getAccessToken,
+  fetch: customFetch,
+});
+```
+
+## Framework adapters
+
+If you're using a framework, reach for the adapter instead of this
+package directly:
+
+- React → [`@universal-everything/sdk-react`](../sdk-react/)
+- Vue 3 → [`@universal-everything/sdk-vue`](../sdk-vue/)
+- Svelte 5 → [`@universal-everything/sdk-svelte`](../sdk-svelte/)
+- Any framework (UI) → [`@universal-everything/ui`](../ui/) (Lit web components)
+- viem integration → [`@universal-everything/sdk-core-viem`](../sdk-core-viem/)

package/dist/index.d.ts

@@ -0,0 +1,542 @@
+type Hex = `0x${string}`;
+type WalletInfo = {
+    walletId: string;
+    address: Hex;
+};
+type ExportedKey = {
+    privateKey: Hex;
+    address: Hex;
+};
+/**
+ * Minimal EVM transaction request shape. Providers may accept richer fields,
+ * but this is the contract.
+ */
+type SignTxRequest = {
+    chainId: number;
+    to?: Hex;
+    data?: Hex;
+    value?: bigint;
+    gas?: bigint;
+    maxFeePerGas?: bigint;
+    maxPriorityFeePerGas?: bigint;
+    nonce?: number;
+    type?: "eip1559" | "legacy" | "eip2930";
+};
+/**
+ * Per-operation context forwarded by the relayer route handler to the
+ * provider. Providers that need user-side per-op authorization (e.g.
+ * Privy's `privy-authorization-signature` header) read from here;
+ * providers that don't (e.g. the in-memory LocalKeyCustodyProvider)
+ * ignore it. Keeping this on every key-touching call lets the relayer
+ * remain provider-agnostic.
+ */
+type KeyCustodyOpContext = {
+    /**
+     * User-side authorization signature. For Privy this is the value of
+     * the `privy-authorization-signature` header the client generated via
+     * `generateAuthorizationSignature(payloadBytes)` from their SDK. The
+     * client signs the canonical request body (RFC 8785) with their
+     * passkey-derived P-256 key; we forward the signature verbatim.
+     */
+    authorizationSignature?: string;
+    /**
+     * Unix-ms timestamp after which the authorization signature is no
+     * longer valid. Forwarded to Privy as `privy-request-expiry`.
+     */
+    requestExpiry?: number;
+};
+/**
+ * Per-wallet operations. The user-to-wallet relationship lives in our DB,
+ * not in the provider — providers only know about backend wallets they
+ * manage, by the opaque walletId they assigned at creation time.
+ */
+interface KeyCustodyProvider {
+    createWallet(opContext?: KeyCustodyOpContext): Promise<WalletInfo>;
+    importWallet(privateKey: Hex, opContext?: KeyCustodyOpContext): Promise<WalletInfo>;
+    exportWallet(walletId: string, opContext?: KeyCustodyOpContext): Promise<ExportedKey>;
+    /** Sign a raw 32-byte hash with no prefix. The LSP-25 path. */
+    signDigest(walletId: string, digest32: Uint8Array | Hex, opContext?: KeyCustodyOpContext): Promise<Hex>;
+    /** EIP-191 v0x45 personal_sign with the "\x19Ethereum Signed Message:\n" prefix. */
+    personalSign(walletId: string, message: string | Uint8Array, opContext?: KeyCustodyOpContext): Promise<Hex>;
+    /** Sign and serialize an EVM transaction for the user to broadcast themselves. */
+    signTransaction(walletId: string, tx: SignTxRequest, opContext?: KeyCustodyOpContext): Promise<Hex>;
+}
+type KeyCustodyErrorCode = "wallet_not_found" | "invalid_private_key" | "invalid_digest" | "invalid_signature" | "provider_unavailable" | "rate_limited";
+declare class KeyCustodyError extends Error {
+    readonly code: KeyCustodyErrorCode;
+    constructor(code: KeyCustodyErrorCode, message: string);
+}
+
+/**
+ * `WalletKitClient` — typed HTTP client over the relayer's `/v1/*`
+ * REST API. Framework-agnostic: uses global `fetch`, no React / Vue /
+ * Privy imports. Consumers (sdk-react, sdk-vue, sdk-svelte, …)
+ * integrate their own auth flow and pass the access token in via
+ * `getAccessToken`.
+ *
+ * Design notes:
+ *
+ * - **Auth shape**: every protected call carries `Authorization:
+ *   Bearer <token>`. The `getAccessToken` callback is invoked fresh
+ *   per request so adapters using Privy's `useAccessToken` (which
+ *   rotates JWTs silently) stay correct without the SDK caching
+ *   anything.
+ * - **Privy per-op signature**: sign / relay endpoints accept an
+ *   optional `opContext` with `authorizationSignature` +
+ *   `requestExpiry`. The SDK forwards those as
+ *   `privy-authorization-signature` + `privy-request-expiry` headers
+ *   per Privy's convention, exactly matching the relayer's
+ *   `opContextFromHeaders` parser.
+ * - **Errors**: non-2xx responses throw `WalletKitError`. The `code`
+ *   field is the server's `error` discriminator (`"profile_not_found"`,
+ *   `"insufficient_quota"`, etc.), mirrored verbatim so consumers can
+ *   `switch` on it.
+ * - **Types**: response shapes are defined here rather than imported
+ *   from the relayer — this package must not depend on the server
+ *   tree. Wire-compatibility is the contract. If a field drifts,
+ *   bump a minor and make it optional first.
+ */
+
+type WalletKitClientConfig = {
+    /** Base URL of the relayer (no trailing slash; the client tolerates either). */
+    baseUrl: string;
+    /**
+     * Fetch-a-token callback. Can be sync or async. Return `null` to
+     * send the request unauthed (which the relayer's auth middleware
+     * will promptly 401 for protected routes).
+     */
+    getAccessToken: () => Promise<string | null> | string | null;
+    /** Fetch override for tests / SSR / custom transport. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+};
+type Wallet = {
+    walletId: string;
+    subject: string;
+    address: Hex;
+    privyWalletId: string;
+    label: string | null;
+    isPrimary: boolean;
+    createdAt: string;
+};
+type ControllerSummary = {
+    controllerId: string;
+    address: Hex;
+    label: string | null;
+    isDefault: boolean;
+    walletId: string | null;
+    isSignable: boolean;
+};
+type ProfileStatus = "active" | "pending_deploy" | "failed_deploy";
+/**
+ * Per-row profile shape — returned by `importProfile`, `deployProfile`,
+ * and `PATCH /v1/profiles/:profileId`. One row per (address, chain).
+ */
+type Profile = {
+    profileId: string;
+    address: Hex;
+    chainId: number;
+    label: string | null;
+    status?: ProfileStatus;
+    defaultControllerId: string | null;
+    controllers: ControllerSummary[];
+    createdAt: string;
+};
+/**
+ * Per-chain status entry inside `ProfileWithChains.chains`. For C.1 each
+ * address has at most one entry; C.2's cross-chain orchestration grows
+ * `chains[]` as queued deploys progress.
+ */
+/**
+ * Cross-chain `deploy_queue` row state. Surfaced on `ChainStatus` so
+ * clients can render queued/submitted progress for cross-chain ops
+ * (Milestone C.2). `null` for single-chain profiles — no queue row
+ * exists.
+ */
+type DeployQueueStatus = "pending_submit" | "submitted" | "mined" | "errored" | "cancelled";
+type ChainStatus = {
+    profileId: string;
+    chainId: number;
+    status: ProfileStatus;
+    label: string | null;
+    defaultControllerId: string | null;
+    controllers: ControllerSummary[];
+    /** Engine tx hash; null until Engine broadcasts. */
+    txHash: string | null;
+    lastUpdatedAt: string;
+    errorMessage: string | null;
+    /** `deploy_queue.status` for cross-chain rows; `null` single-chain. */
+    queueStatus: DeployQueueStatus | null;
+};
+/**
+ * Address-grouped profile shape — returned by `listProfiles` and
+ * `getProfileByAddress`. Address is the natural primary key once a UP
+ * may live on multiple chains (handoff G1).
+ */
+type ProfileWithChains = {
+    address: Hex;
+    chains: ChainStatus[];
+};
+type QuotaSnapshot = {
+    subject: string;
+    periodStart: string;
+    includedRemaining: string;
+    topupRemaining: string;
+    total: string;
+};
+/**
+ * A paid subscription snapshot (from `GET /v1/billing/subscription`).
+ * `tier` is left as `string` so a server-side tier addition doesn't
+ * require an SDK bump to read.
+ */
+type SubscriptionSnapshot = {
+    subject: string;
+    tier: string;
+    /** `'active' | 'trialing'` mean feature access is granted. */
+    status: string;
+    source: "stripe" | "apple" | "google";
+    externalId: string;
+    currentPeriodEnd: string | null;
+};
+/**
+ * The synthesized free-tier default — the shape returned when the user
+ * has no paid subscription. `source === null` is the discriminant.
+ */
+type FreeDefaultSnapshot = {
+    subject: string;
+    tier: "free";
+    status: "active";
+    source: null;
+    externalId: null;
+    currentPeriodEnd: null;
+};
+type SubscriptionResponse = SubscriptionSnapshot | FreeDefaultSnapshot;
+/** Stripe-hosted Checkout session (from `POST /v1/billing/checkout-session`). */
+type CheckoutSession = {
+    id: string;
+    url: string;
+};
+type OpenCheckoutInput = {
+    /** Only `"pro"` is purchasable today; the server 400s any other tier. */
+    tier: "pro";
+    /** Deep link for a mobile in-app browser sheet to hop back into the host app. */
+    returnDeepLink?: string;
+    /** Origin Stripe returns to after checkout. Defaults to `window.location.origin` in a browser. */
+    returnOrigin?: string;
+    /**
+     * Browser only: navigate to the Stripe URL after creating the session.
+     * Defaults to `true`. Set `false` to just get `{ url }` back and open it
+     * yourself (native in-app sheet, popup, etc.). No-op with no `window`.
+     */
+    redirect?: boolean;
+};
+type OpContext = {
+    authorizationSignature: string;
+    requestExpiry?: number;
+};
+type SignTransactionInput = {
+    chainId: number;
+    to?: Hex;
+    data?: Hex;
+    value?: string;
+    gas?: string;
+    maxFeePerGas?: string;
+    maxPriorityFeePerGas?: string;
+    nonce?: number;
+    type?: "eip1559" | "legacy" | "eip2930";
+};
+type SignTransactionResponse = {
+    rawTx: Hex;
+    walletId: string;
+    address: Hex;
+    chainId: number;
+};
+type SignMessageResponse = {
+    signature: Hex;
+    walletId: string;
+    address: Hex;
+};
+type SignLsp25Input = {
+    profileId: string;
+    controllerId?: string;
+    value: string;
+    calldata: Hex;
+    nonce: string;
+    validityTimestamps: string;
+};
+type SignLsp25Response = {
+    signature: Hex;
+    digest: Hex;
+    profileId: string;
+    controllerId: string;
+    controllerAddress: Hex;
+    target: Hex;
+    chainId: number;
+    nonce: string;
+    validityTimestamps: string;
+    value: string;
+    calldata: Hex;
+};
+type RelaySponsoredInput = {
+    profileId: string;
+    controllerId?: string;
+    value: string;
+    calldata: Hex;
+    validityTimestamps?: string;
+    channel?: string;
+};
+type RelaySponsoredResponse = {
+    queueId: string;
+    nonce: string;
+    channel: string;
+    profileId: string;
+    controllerId: string;
+    controllerAddress: Hex;
+    target: Hex;
+    chainId: number;
+    signature: Hex;
+};
+/**
+ * A1 control proof accompanying an external `controllerAddress` deploy — a
+ * signature by that address over a nonce-bound challenge (see
+ * `@universal-everything/sdk-core-viem`'s `buildControlProof`). The
+ * `nonce` comes from {@link WalletKitClient.getNonce}.
+ */
+type ControlProof = {
+    /** 65-byte EIP-191 signature (0x-prefixed, 132 chars) by `controllerAddress`. */
+    signature: Hex;
+    /** Single-use nonce from `POST /v1/auth/nonce`. */
+    nonce: string;
+    /** Signature issuance time, unix seconds (server freshness-checks it). */
+    issuedAtUnix: number;
+};
+type NonceResponse = {
+    nonce: string;
+    issuedAt: string;
+};
+type DeployProfileBase = {
+    chainId: number;
+    label?: string | null;
+    predictedAddress: Hex;
+    deploymentCalldata: Hex;
+    /**
+     * Multi-chain target set. When length > 1 the response is
+     * {@link DeployProfileMultiChainResponse}; the user's current chain
+     * (`chainId`) must be included. Single-chain (`undefined` or
+     * length 1) returns {@link DeployProfileSingleChainResponse} as before.
+     * External-controller (A1) deploys are single-chain only.
+     */
+    chains?: number[];
+};
+/**
+ * Deploy a sponsored Universal Profile. Two mutually-exclusive controller
+ * modes:
+ * - **custody**: `controllerWalletId` — a relayer-held wallet row.
+ * - **external (A1)**: `controllerAddress` + `controlProof` — a user-held key
+ *   (a Privy embedded wallet, or an extension/mobile key) that proves control
+ *   by signing a nonce-bound challenge. Build the proof with
+ *   `@universal-everything/sdk-core-viem`'s `buildControlProof`.
+ */
+type DeployProfileInput = (DeployProfileBase & {
+    controllerWalletId: string;
+    controllerAddress?: never;
+    controlProof?: never;
+}) | (DeployProfileBase & {
+    controllerAddress: Hex;
+    controlProof: ControlProof;
+    controllerWalletId?: never;
+});
+type DeployProfileSingleChainResponse = {
+    multiChain: false;
+    profileId: string;
+    predictedAddress: Hex;
+    chainId: number;
+    engineTxId: string;
+    status: "pending_deploy";
+};
+type DeployProfileMultiChainResponse = {
+    multiChain: true;
+    opId: string;
+    predictedAddress: Hex;
+    chains: Array<{
+        chainId: number;
+        profileId: string;
+        queueId: string;
+        queueStatus: "submitted" | "pending_submit";
+        engineTxId: string | null;
+    }>;
+};
+type DeployProfileResponse = DeployProfileSingleChainResponse | DeployProfileMultiChainResponse;
+type ImportBeginResponse = {
+    importId: string;
+    serverPublicKey: Hex;
+    expiresAt: string;
+};
+type ImportCompleteInput = {
+    importId: string;
+    clientPublicKey: Hex;
+    sealed: Hex;
+    label?: string | null;
+};
+type ImportCompleteResponse = {
+    walletId: string;
+    address: Hex;
+    linkedControllers: number;
+};
+type ExportRequestInput = {
+    walletId: string;
+    clientPublicKey: Hex;
+};
+type ExportRequestResponse = {
+    exportId: string;
+    availableAt: string;
+    expiresAt: string;
+};
+type ExportCompleteResponse = {
+    sealed: Hex;
+    serverPublicKey: Hex;
+    address: Hex;
+};
+declare class WalletKitError extends Error {
+    readonly status: number;
+    /** Server's `error` discriminator, or `"network_error"` on transport failure. */
+    readonly code: string;
+    readonly body: unknown;
+    constructor(status: number, code: string, message: string, body: unknown);
+}
+/**
+ * Server `error` discriminators that represent a billing / plan-limit
+ * wall — either 402 "out of quota" (buy more) or 403 "your tier doesn't
+ * include this" (upgrade). `#request` promotes any response carrying one
+ * of these codes to a {@link TierError}. `chain_unavailable` (503) is
+ * deliberately absent: it's an operator-side outage, not the caller's plan.
+ */
+declare const TIER_ERROR_CODES: ReadonlySet<string>;
+/**
+ * A billing / plan-limit condition — the caller hit a quota or a tier
+ * boundary the server refuses to cross. Subclass of {@link WalletKitError}
+ * so existing `instanceof WalletKitError` handling still catches it, while
+ * `instanceof TierError` lets a host app show an upgrade / top-up prompt
+ * instead of a generic failure. Switch on `.code` for the specific wall
+ * (see {@link TIER_ERROR_CODES}).
+ *
+ * The typed getters are conveniences over `body`; each is populated only
+ * for the codes whose payload carries that field (e.g. `allowedChains`
+ * on `tier_not_allowed_for_chain`), and `undefined` otherwise. `body`
+ * remains the source of truth.
+ */
+declare class TierError extends WalletKitError {
+    #private;
+    constructor(status: number, code: string, message: string, body: unknown);
+    /** Caller's current tier, when the server reports it (`tier` / `currentTier`). */
+    get tier(): string | undefined;
+    /** Chains the current tier may use (`tier_not_allowed_for_chain`). */
+    get allowedChains(): number[] | undefined;
+    /** Units requested (`insufficient_quota`). Stringified bigint from the server. */
+    get requested(): string | undefined;
+    /** Units available (`insufficient_quota`). Stringified bigint from the server. */
+    get available(): string | undefined;
+    /** The cap that was hit (`cross_chain_capacity_exceeded` / `kind_profile_cap_exceeded`). */
+    get cap(): number | undefined;
+    /** Current count against the cap. */
+    get current(): number | undefined;
+    /** Profile kind the cap applies to (`kind_*` / `cross_chain_*`). */
+    get kind(): string | undefined;
+    /** Chain id the tier didn't allow (`tier_not_allowed_for_chain`). */
+    get chainId(): number | undefined;
+}
+declare class WalletKitClient {
+    #private;
+    constructor(config: WalletKitClientConfig);
+    me(): Promise<{
+        subject: string;
+        isAdmin: boolean;
+    }>;
+    listWallets(): Promise<Wallet[]>;
+    getWallet(walletId: string): Promise<Wallet>;
+    createWallet(input?: {
+        label?: string | null;
+    }): Promise<Wallet>;
+    patchWallet(walletId: string, patch: {
+        label?: string | null;
+        isPrimary?: boolean;
+    }): Promise<Wallet>;
+    deleteWallet(walletId: string): Promise<{
+        walletId: string;
+    }>;
+    listProfiles(): Promise<ProfileWithChains[]>;
+    /**
+     * Address-keyed lookup. Returns the single address-grouped entry,
+     * with `chains[]` populated (length 1 for single-chain UPs).
+     */
+    getProfileByAddress(address: Hex): Promise<ProfileWithChains>;
+    deployProfile(input: DeployProfileInput): Promise<DeployProfileResponse>;
+    /**
+     * Fetch a single-use nonce (`POST /v1/auth/nonce`, public — no auth). Used to
+     * bind an A1 control proof for an external-controller {@link deployProfile}.
+     */
+    getNonce(): Promise<NonceResponse>;
+    importProfile(input: {
+        address: Hex;
+        chainId: number;
+        controllerWalletId: string;
+        label?: string | null;
+    }): Promise<Profile>;
+    signTransaction(input: SignTransactionInput, opts?: {
+        walletId?: string;
+        opContext?: OpContext;
+    }): Promise<SignTransactionResponse>;
+    signMessage(message: string, opts?: {
+        walletId?: string;
+        encoding?: "utf-8" | "hex";
+        opContext?: OpContext;
+    }): Promise<SignMessageResponse>;
+    signLsp25(input: SignLsp25Input, opContext?: OpContext): Promise<SignLsp25Response>;
+    relaySponsored(input: RelaySponsoredInput, opContext?: OpContext): Promise<RelaySponsoredResponse>;
+    getQuota(): Promise<QuotaSnapshot>;
+    /**
+     * The caller's current subscription, or the synthesized free-tier
+     * default (`source === null`) when they have no paid subscription.
+     */
+    getSubscription(): Promise<SubscriptionResponse>;
+    /**
+     * Start a Stripe Checkout for a tier and return the created session
+     * `{ id, url }`. In a browser this ALSO navigates to `url` by default
+     * (opt out with `{ redirect: false }` to open the URL yourself — mobile
+     * in-app sheet, popup, etc.). Headless / SSR: no `window` ⇒ no
+     * navigation, the session is simply returned.
+     *
+     * Server errors surface as `WalletKitError` — notably `409
+     * subscription_exists` (already subscribed) and `400 tier_not_purchasable`.
+     */
+    openCheckout(input: OpenCheckoutInput): Promise<CheckoutSession>;
+    beginKeyImport(): Promise<ImportBeginResponse>;
+    completeKeyImport(input: ImportCompleteInput): Promise<ImportCompleteResponse>;
+    requestKeyExport(input: ExportRequestInput): Promise<ExportRequestResponse>;
+    cancelKeyExport(exportId: string): Promise<{
+        ok: true;
+        exportId: string;
+    }>;
+    completeKeyExport(exportId: string): Promise<ExportCompleteResponse>;
+}
+/** Factory mirroring other `createX` helpers in this workspace. */
+declare function createWalletKitClient(config: WalletKitClientConfig): WalletKitClient;
+
+type Subject = string;
+type VerifiedToken = {
+    subject: Subject;
+    claims: Record<string, unknown>;
+};
+type VerifyOptions = {
+    audience?: string | string[];
+    authorizedParties?: string[];
+};
+interface IdentityProvider {
+    verifyToken(token: string, opts?: VerifyOptions): Promise<VerifiedToken>;
+}
+type IdentityErrorCode = "missing_token" | "invalid_token" | "expired_token" | "missing_subject" | "azp_mismatch" | "issuer_mismatch" | "audience_mismatch" | "jwks_unavailable" | "provider_unavailable";
+declare class IdentityError extends Error {
+    readonly code: IdentityErrorCode;
+    constructor(code: IdentityErrorCode, message: string);
+}
+
+export { type ChainStatus, type CheckoutSession, type ControlProof, type ControllerSummary, type DeployProfileInput, type DeployProfileMultiChainResponse, type DeployProfileResponse, type DeployProfileSingleChainResponse, type DeployQueueStatus, type ExportCompleteResponse, type ExportRequestInput, type ExportRequestResponse, type ExportedKey, type FreeDefaultSnapshot, type Hex, IdentityError, type IdentityErrorCode, type IdentityProvider, type ImportBeginResponse, type ImportCompleteInput, type ImportCompleteResponse, KeyCustodyError, type KeyCustodyErrorCode, type KeyCustodyOpContext, type KeyCustodyProvider, type NonceResponse, type OpContext, type OpenCheckoutInput, type Profile, type ProfileStatus, type ProfileWithChains, type QuotaSnapshot, type RelaySponsoredInput, type RelaySponsoredResponse, type SignLsp25Input, type SignLsp25Response, type SignMessageResponse, type SignTransactionInput, type SignTransactionResponse, type SignTxRequest, type Subject, type SubscriptionResponse, type SubscriptionSnapshot, TIER_ERROR_CODES, TierError, type VerifiedToken, type VerifyOptions, type Wallet, type WalletInfo, WalletKitClient, type WalletKitClientConfig, WalletKitError, createWalletKitClient };

package/dist/index.js

@@ -0,0 +1,289 @@
+// src/client.ts
+var WalletKitError = class extends Error {
+  status;
+  /** Server's `error` discriminator, or `"network_error"` on transport failure. */
+  code;
+  body;
+  constructor(status, code, message, body) {
+    super(message);
+    this.name = "WalletKitError";
+    this.status = status;
+    this.code = code;
+    this.body = body;
+  }
+};
+var TIER_ERROR_CODES = /* @__PURE__ */ new Set([
+  "insufficient_quota",
+  "tier_not_allowed_for_chain",
+  "cross_chain_capacity_exceeded",
+  "cross_chain_chain_not_eligible",
+  "kind_profile_cap_exceeded"
+]);
+var TierError = class extends WalletKitError {
+  constructor(status, code, message, body) {
+    super(status, code, message, body);
+    this.name = "TierError";
+  }
+  #field(key) {
+    return typeof this.body === "object" && this.body !== null && key in this.body ? this.body[key] : void 0;
+  }
+  /** Caller's current tier, when the server reports it (`tier` / `currentTier`). */
+  get tier() {
+    return this.#field("currentTier") ?? this.#field("tier");
+  }
+  /** Chains the current tier may use (`tier_not_allowed_for_chain`). */
+  get allowedChains() {
+    return this.#field("allowedChains");
+  }
+  /** Units requested (`insufficient_quota`). Stringified bigint from the server. */
+  get requested() {
+    return this.#field("requested");
+  }
+  /** Units available (`insufficient_quota`). Stringified bigint from the server. */
+  get available() {
+    return this.#field("available");
+  }
+  /** The cap that was hit (`cross_chain_capacity_exceeded` / `kind_profile_cap_exceeded`). */
+  get cap() {
+    return this.#field("cap");
+  }
+  /** Current count against the cap. */
+  get current() {
+    return this.#field("current");
+  }
+  /** Profile kind the cap applies to (`kind_*` / `cross_chain_*`). */
+  get kind() {
+    return this.#field("kind");
+  }
+  /** Chain id the tier didn't allow (`tier_not_allowed_for_chain`). */
+  get chainId() {
+    return this.#field("chainId");
+  }
+};
+var WalletKitClient = class {
+  #baseUrl;
+  #getAccessToken;
+  #fetch;
+  constructor(config) {
+    if (!config.baseUrl) throw new Error("WalletKitClient: baseUrl required");
+    this.#baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.#getAccessToken = config.getAccessToken;
+    this.#fetch = config.fetch ?? ((input, init) => fetch(input, init));
+  }
+  // --- identity ---
+  async me() {
+    return this.#request("GET", "/v1/me");
+  }
+  // --- wallets ---
+  async listWallets() {
+    return (await this.#request("GET", "/v1/wallets")).wallets;
+  }
+  async getWallet(walletId) {
+    return this.#request("GET", `/v1/wallets/${encodeURIComponent(walletId)}`);
+  }
+  async createWallet(input = {}) {
+    return this.#request("POST", "/v1/wallets", input);
+  }
+  async patchWallet(walletId, patch) {
+    return this.#request(
+      "PATCH",
+      `/v1/wallets/${encodeURIComponent(walletId)}`,
+      patch
+    );
+  }
+  async deleteWallet(walletId) {
+    return this.#request(
+      "DELETE",
+      `/v1/wallets/${encodeURIComponent(walletId)}`
+    );
+  }
+  // --- profiles ---
+  async listProfiles() {
+    return (await this.#request(
+      "GET",
+      "/v1/profiles"
+    )).profiles;
+  }
+  /**
+   * Address-keyed lookup. Returns the single address-grouped entry,
+   * with `chains[]` populated (length 1 for single-chain UPs).
+   */
+  async getProfileByAddress(address) {
+    return this.#request("GET", `/v1/profiles/${encodeURIComponent(address)}`);
+  }
+  async deployProfile(input) {
+    return this.#request("POST", "/v1/profiles", input);
+  }
+  /**
+   * Fetch a single-use nonce (`POST /v1/auth/nonce`, public — no auth). Used to
+   * bind an A1 control proof for an external-controller {@link deployProfile}.
+   */
+  async getNonce() {
+    return this.#request("POST", "/v1/auth/nonce");
+  }
+  async importProfile(input) {
+    return this.#request("POST", "/v1/profiles/import", input);
+  }
+  // --- signing ---
+  async signTransaction(input, opts = {}) {
+    return this.#request(
+      "POST",
+      "/v1/sign/transaction",
+      { walletId: opts.walletId, tx: input },
+      opts.opContext
+    );
+  }
+  async signMessage(message, opts = {}) {
+    return this.#request(
+      "POST",
+      "/v1/sign/message",
+      { walletId: opts.walletId, message, encoding: opts.encoding },
+      opts.opContext
+    );
+  }
+  async signLsp25(input, opContext) {
+    return this.#request("POST", "/v1/sign/lsp25", input, opContext);
+  }
+  // --- relay ---
+  async relaySponsored(input, opContext) {
+    return this.#request("POST", "/v1/relay/sponsored", input, opContext);
+  }
+  // --- quota ---
+  async getQuota() {
+    return this.#request("GET", "/v1/quota");
+  }
+  // --- billing ---
+  /**
+   * The caller's current subscription, or the synthesized free-tier
+   * default (`source === null`) when they have no paid subscription.
+   */
+  async getSubscription() {
+    return this.#request("GET", "/v1/billing/subscription");
+  }
+  /**
+   * Start a Stripe Checkout for a tier and return the created session
+   * `{ id, url }`. In a browser this ALSO navigates to `url` by default
+   * (opt out with `{ redirect: false }` to open the URL yourself — mobile
+   * in-app sheet, popup, etc.). Headless / SSR: no `window` ⇒ no
+   * navigation, the session is simply returned.
+   *
+   * Server errors surface as `WalletKitError` — notably `409
+   * subscription_exists` (already subscribed) and `400 tier_not_purchasable`.
+   */
+  async openCheckout(input) {
+    const loc = globalThis.window?.location;
+    const returnOrigin = input.returnOrigin ?? loc?.origin;
+    const session = await this.#request(
+      "POST",
+      "/v1/billing/checkout-session",
+      {
+        tier: input.tier,
+        ...input.returnDeepLink ? { returnDeepLink: input.returnDeepLink } : {},
+        ...returnOrigin ? { returnOrigin } : {}
+      }
+    );
+    if (input.redirect !== false && loc) {
+      loc.href = session.url;
+    }
+    return session;
+  }
+  // --- key import / export ---
+  async beginKeyImport() {
+    return this.#request("GET", "/v1/keys/import/begin");
+  }
+  async completeKeyImport(input) {
+    return this.#request("POST", "/v1/keys/import/complete", input);
+  }
+  async requestKeyExport(input) {
+    return this.#request("POST", "/v1/keys/export/request", input);
+  }
+  async cancelKeyExport(exportId) {
+    return this.#request("POST", "/v1/keys/export/cancel", { exportId });
+  }
+  async completeKeyExport(exportId) {
+    return this.#request("POST", "/v1/keys/export/complete", { exportId });
+  }
+  // ----------------------------------------------------------------------
+  // internals
+  // ----------------------------------------------------------------------
+  async #request(method, path, body, opContext) {
+    const token = await this.#getAccessToken();
+    const headers = {};
+    if (token) headers.Authorization = `Bearer ${token}`;
+    if (body !== void 0) headers["Content-Type"] = "application/json";
+    if (opContext?.authorizationSignature) {
+      headers["privy-authorization-signature"] = opContext.authorizationSignature;
+      if (opContext.requestExpiry !== void 0) {
+        headers["privy-request-expiry"] = String(opContext.requestExpiry);
+      }
+    }
+    let response;
+    try {
+      response = await this.#fetch(`${this.#baseUrl}${path}`, {
+        method,
+        headers,
+        body: body === void 0 ? void 0 : JSON.stringify(body)
+      });
+    } catch (err) {
+      throw new WalletKitError(
+        0,
+        "network_error",
+        `${method} ${path} transport failed: ${err instanceof Error ? err.message : String(err)}`,
+        null
+      );
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    const text = await response.text();
+    let parsed;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+    }
+    if (!response.ok) {
+      const code = typeof parsed === "object" && parsed !== null && "error" in parsed ? String(parsed.error) : `http_${response.status}`;
+      const msg = typeof parsed === "object" && parsed !== null && "message" in parsed ? String(parsed.message) : text || response.statusText;
+      if (TIER_ERROR_CODES.has(code)) {
+        throw new TierError(response.status, code, msg, parsed);
+      }
+      throw new WalletKitError(response.status, code, msg, parsed);
+    }
+    return parsed;
+  }
+};
+function createWalletKitClient(config) {
+  return new WalletKitClient(config);
+}
+
+// src/identity.ts
+var IdentityError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "IdentityError";
+    this.code = code;
+  }
+};
+
+// src/key-custody.ts
+var KeyCustodyError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "KeyCustodyError";
+    this.code = code;
+  }
+};
+export {
+  IdentityError,
+  KeyCustodyError,
+  TIER_ERROR_CODES,
+  TierError,
+  WalletKitClient,
+  WalletKitError,
+  createWalletKitClient
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@universal-everything/sdk-core",
+  "version": "1.0.0-dev.cb4e80f",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/universal-everything/universal-relayer.git",
+    "directory": "packages/sdk-core"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.10",
+    "tsup": "^8.5.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsup"
+  }
+}