@universal-everything/sdk-core 1.1.0 → 1.2.0-dev.0a281f1

package/dist/index.d.ts

@@ -139,6 +139,8 @@ type Profile = {
     status?: ProfileStatus;
     defaultControllerId: string | null;
     controllers: ControllerSummary[];
+    /** The owner-level deploy-time controller (lowercase) or `null` = unknown. */
+    generatingController: string | null;
     createdAt: string;
 };
 /**
@@ -157,6 +159,12 @@ type ChainStatus = {
     profileId: string;
     chainId: number;
     status: ProfileStatus;
+    /**
+     * The owner-level controller the LSP23 deploy granted (lowercase), or
+     * `null` = unknown. Clients compare it with their own keystore to tell a
+     * *created* profile from an *Imported* (secondary-key) one.
+     */
+    generatingController: string | null;
     label: string | null;
     defaultControllerId: string | null;
     controllers: ControllerSummary[];
@@ -172,8 +180,170 @@ type ChainStatus = {
  * `getProfileByAddress`. Address is the natural primary key once a UP
  * may live on multiple chains (handoff G1).
  */
+/** A subscription currently covering an identity. */
+type CoveredBy = {
+    subscriptionId: string;
+    /**
+     * `self` = owned by the caller's account. `other` (a foreign covering
+     * subscription) is reserved for R2's explicit membership — the server only
+     * emits `self` today.
+     */
+    owner: "self" | "other";
+    tier: string;
+    status: string;
+    source: string;
+};
+/**
+ * Server-side extend verdict — ADVISORY. `reason` reports the ownership and
+ * capacity gates the extend route enforces for this session; target-dependent
+ * gates (chain availability, tier chain allow-list, LSP23 package / factory /
+ * deployability) come from `extend-targets` and at submit, so `null` means
+ * "no ownership or capacity refusal", not "extend will succeed". Whether THIS
+ * device can extend (holds the generating key) is the client's call from
+ * `generatingController`.
+ */
+type ExtendVerdictReason = "not_active" | "held_by_another_login" | "subscription_required" | "cross_chain_cap_reached" | "capacity_unknown";
+type ExtendVerdict = {
+    /**
+     * Chains the identity is live on (active / pending), across every login of
+     * the holder account — NOT candidate targets; those come from
+     * `GET /v1/profiles/:id/extend-targets`, whose occupancy check is scoped to
+     * the calling login.
+     */
+    chains: number[];
+    reason: ExtendVerdictReason | null;
+};
+/** A store the relayer sells through. The tiers are the same in every store. */
+type BillingStore = "stripe" | "apple" | "google";
+/** One purchasable item of a plan in one store — see {@link RelayerClient.getCatalog}. */
+type CatalogProduct = {
+    store: BillingStore;
+    /**
+     * The id the store knows the item by: the Stripe Price id, the App Store /
+     * Play product id. On Apple / Google, fetch the localized title and price
+     * from StoreKit / Play Billing with it — those are what the user must see.
+     */
+    externalProductId: string;
+    displayName: string;
+    /** Stripe: the charged amount. Apple / Google: a reference price only. */
+    amountCents: number | null;
+    currency: string | null;
+    /** Stripe only; always `false` / `0` for Apple / Google (attach order). */
+    isDefault: boolean;
+    sortOrder: number;
+    /** What the store needs besides the id (Play `basePlanId`); `{}` for Stripe. */
+    metadata: Record<string, unknown>;
+    productName: string | null;
+    productDescription: string | null;
+};
+/** The plan's default Stripe Price — see {@link CatalogPlan.defaultPrice}. */
+type CatalogDefaultPrice = {
+    stripePriceId: string;
+    displayName: string;
+    amountCents: number | null;
+    currency: string | null;
+    stripeMode: "test" | "live";
+    productName: string | null;
+    productDescription: string | null;
+};
+/** One plan of `GET /v1/billing/catalog` — what it grants and what buys it. */
+type CatalogPlan = {
+    /** `tier:<name>` for subscriptions, `pack:<name>` for one-time packs. */
+    key: string;
+    label: string;
+    description: string | null;
+    audience: "user" | "dev";
+    cadence: string;
+    /** What a store page groups by. `interval` is null for a one-time purchase. */
+    kind: "subscription" | "one_time";
+    interval: "day" | "month" | "year" | null;
+    stackable: boolean;
+    /** Only purchasable on top of a live subscription. */
+    requiresSubscription: boolean;
+    mainnetProfileCap: number;
+    testnetProfileCap: number;
+    crossChainDeployCap: number;
+    crossChainTestnetCap: number;
+    crossChainEnabledChains: number[];
+    overageEnabled: boolean;
+    overageCapCredits: string | null;
+    /** Gas budget per period in credits (1 credit = €1), decimal string. */
+    credits: string | null;
+    gasCreditsPerChain: Record<string, string>;
+    /**
+     * The default Stripe Price, whatever `store` was requested (null = none
+     * attached). Predates `products`; a store page reads `products`.
+     */
+    defaultPrice: CatalogDefaultPrice | null;
+    /** Active items for the requested store. */
+    products: CatalogProduct[];
+};
+type Catalog = {
+    audience: "user" | "dev";
+    store: BillingStore;
+    plans: CatalogPlan[];
+};
+/** One entry of `GET /v1/subscriptions` — a subscription of the caller's account. */
+type SubscriptionSummary = {
+    subscriptionId: string;
+    /** Always `self` today; `other` (a subscription that only covers one of your profiles) arrives with explicit membership. */
+    owner: "self" | "other";
+    tier: string;
+    status: string;
+    /** `active` or `trialing`. */
+    live: boolean;
+    source: "stripe" | "apple" | "google" | "admin";
+    /** Bought in the store sandbox (TestFlight / App Review / sandbox tester) — no real money. */
+    sandbox: boolean;
+    currentPeriodEnd: string | null;
+    /** Where Manage goes: `stripe` ⇒ {@link RelayerClient.createPortalSession}; `apple` / `google` ⇒ the store; `admin` ⇒ nothing. */
+    manage: {
+        kind: "stripe" | "apple" | "google" | "admin";
+    };
+};
+/**
+ * Result of {@link RelayerClient.submitAppleTransaction} /
+ * {@link RelayerClient.claimSubscription}. `applied: false` with a `reason`
+ * is bookkeeping, not an error: `stale` (an older period than the relayer
+ * already has), `upgraded` (superseded — the upgrade's own transaction
+ * follows), `refund_of_past_period`, `refund_unknown_subscription`.
+ */
+type StoreTransactionResult = {
+    applied: true;
+    status: "active" | "past_due" | "expired" | "refunded";
+    tier: string;
+} | {
+    applied: false;
+    reason: string;
+};
+/** `GET /v1/me` — the authenticated login and its account context. */
+type Me = {
+    subject: string;
+    isAdmin: boolean;
+    /** The login's personal account (null only before provisioning). */
+    accountId: string | null;
+    /** This login's own tier — what the cross-chain cap resolves from. */
+    tier: string;
+    /**
+     * The account's effective tier (best tier across its login subjects) —
+     * what gas coverage resolves from. Differs from `tier` only on legacy
+     * multi-login accounts.
+     */
+    accountTier: string;
+};
 type ProfileWithChains = {
     address: Hex;
+    /**
+     * Identity-level generating controller: the value every chain row agrees
+     * on; `null` when unknown or when the rows disagree.
+     */
+    generatingController: string | null;
+    /**
+     * Present on the `/v1/profiles` mount; omitted on the sig-auth
+     * `/v1/relayer/profiles` mirror.
+     */
+    coveredBy?: CoveredBy[];
+    extend: ExtendVerdict;
     chains: ChainStatus[];
 };
 type QuotaSnapshot = {
@@ -313,6 +483,11 @@ type NonceResponse = {
     nonce: string;
     issuedAt: string;
 };
+/** `POST /v1/ipfs/upload-token` — a short-lived bearer for the IPFS upload service. */
+type IpfsUploadTokenResponse = {
+    token: string;
+    expiresAt: string;
+};
 type DeployProfileBase = {
     chainId: number;
     label?: string | null;
@@ -331,10 +506,17 @@ type DeployProfileBase = {
  * 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
+ * - **external (A1)**: `controllerAddress` (+ `controlProof`) — a user-held key
+ *   (a Privy embedded wallet, or an extension/mobile key). The proof is a
+ *   signature by that key over a nonce-bound challenge; build it with
  *   `@universal-everything/sdk-core-viem`'s `buildControlProof`.
+ *
+ * On `/v1` the proof is **optional**: a first-time user has only a social
+ * login, and the extension / mobile app holding the new controller cannot sign
+ * for a not-yet-deployed profile. When present it is always verified. The next
+ * API version makes it mandatory for everyone (relayer
+ * `docs/DESIGN_2026-09-10_control-proof-versioning.md`), so callers that CAN
+ * sign (a Privy embedded wallet) should always send it.
  */
 type DeployProfileInput = (DeployProfileBase & {
     controllerWalletId: string;
@@ -342,7 +524,7 @@ type DeployProfileInput = (DeployProfileBase & {
     controlProof?: never;
 }) | (DeployProfileBase & {
     controllerAddress: Hex;
-    controlProof: ControlProof;
+    controlProof?: ControlProof;
     controllerWalletId?: never;
 });
 type DeployProfileSingleChainResponse = {
@@ -447,10 +629,7 @@ declare class TierError extends WalletKitError {
 declare class WalletKitClient {
     #private;
     constructor(config: WalletKitClientConfig);
-    me(): Promise<{
-        subject: string;
-        isAdmin: boolean;
-    }>;
+    me(): Promise<Me>;
     listWallets(): Promise<Wallet[]>;
     getWallet(walletId: string): Promise<Wallet>;
     createWallet(input?: {
@@ -475,6 +654,14 @@ declare class WalletKitClient {
      * bind an A1 control proof for an external-controller {@link deployProfile}.
      */
     getNonce(): Promise<NonceResponse>;
+    /**
+     * Mint a short-lived (~120s) HS256 token for the IPFS upload service
+     * (`POST /v1/ipfs/upload-token`, authenticated). Fetch one per upload:
+     * the token is meant to expire within the service's 600s window (which the
+     * service does not enforce today — see the relayer's routes/ipfs.ts). 503
+     * when the relayer has no upload secret configured.
+     */
+    getIpfsUploadToken(): Promise<IpfsUploadTokenResponse>;
     importProfile(input: {
         address: Hex;
         chainId: number;
@@ -498,6 +685,56 @@ declare class WalletKitClient {
      * default (`source === null`) when they have no paid subscription.
      */
     getSubscription(): Promise<SubscriptionResponse>;
+    /**
+     * What can be bought, per store — what a store page renders. With `store`
+     * the list holds only the plans purchasable there plus the free tier;
+     * without it every active plan comes back with its Stripe products (empty
+     * = not purchasable yet). The layout is the caller's: group by `kind` /
+     * `interval`; Stripe products arrive in `sortOrder`.
+     */
+    getCatalog(opts?: {
+        audience?: "user" | "dev";
+        store?: BillingStore;
+    }): Promise<Catalog>;
+    /**
+     * Every subscription of the caller's account, live ones first — what the
+     * dashboard's account / subscription dropdown renders.
+     */
+    listSubscriptions(): Promise<{
+        subscriptions: SubscriptionSummary[];
+    }>;
+    /**
+     * Hand a StoreKit 2 purchase to the relayer (DEV-16570): pass the
+     * transaction's `jwsRepresentation` after a purchase and for every
+     * `Transaction.updates` entry. Purchase with `appAccountToken` = the
+     * caller's `accountId` from {@link RelayerClient.me}; a transaction bought
+     * for another account rejects with `403 app_account_token_mismatch`, one
+     * attached to another account with `409 held_by_another_account` — restore
+     * those with {@link RelayerClient.claimSubscription}. `422 unmapped_product`
+     * = the product id is not in the catalog.
+     */
+    submitAppleTransaction(signedTransaction: string): Promise<StoreTransactionResult>;
+    /**
+     * Restore purchases: move a store subscription onto the caller's account
+     * (single owner — the previous account loses it). Pass a signed transaction
+     * from `Transaction.currentEntitlements`; only a device signed in with the
+     * purchasing Apple ID can produce one. A subscription moves to a different
+     * account at most once per calendar month: `409 claim_cooldown` otherwise.
+     */
+    claimSubscription(input: {
+        store: "apple";
+        signedTransaction: string;
+    }): Promise<StoreTransactionResult>;
+    /**
+     * Stripe Customer Portal URL for the caller's own Stripe subscription.
+     * Rejects with `manage_in_store` (409) for an Apple / Google subscription
+     * and `no_subscription` (404) when there is nothing to manage.
+     */
+    createPortalSession(opts?: {
+        returnOrigin?: string;
+    }): Promise<{
+        url: string;
+    }>;
     /**
      * Start a Stripe Checkout for a tier and return the created session
      * `{ id, url }`. In a browser this ALSO navigates to `url` by default
@@ -539,4 +776,4 @@ declare class IdentityError extends Error {
     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 };
+export { type BillingStore, type Catalog, type CatalogDefaultPrice, type CatalogPlan, type CatalogProduct, type ChainStatus, type CheckoutSession, type ControlProof, type ControllerSummary, type CoveredBy, type DeployProfileInput, type DeployProfileMultiChainResponse, type DeployProfileResponse, type DeployProfileSingleChainResponse, type DeployQueueStatus, type ExportCompleteResponse, type ExportRequestInput, type ExportRequestResponse, type ExportedKey, type ExtendVerdict, type ExtendVerdictReason, type FreeDefaultSnapshot, type Hex, IdentityError, type IdentityErrorCode, type IdentityProvider, type ImportBeginResponse, type ImportCompleteInput, type ImportCompleteResponse, type IpfsUploadTokenResponse, KeyCustodyError, type KeyCustodyErrorCode, type KeyCustodyOpContext, type KeyCustodyProvider, type Me, 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 StoreTransactionResult, type Subject, type SubscriptionResponse, type SubscriptionSnapshot, type SubscriptionSummary, TIER_ERROR_CODES, TierError, type VerifiedToken, type VerifyOptions, type Wallet, type WalletInfo, WalletKitClient, type WalletKitClientConfig, WalletKitError, createWalletKitClient };

package/dist/index.js

@@ -121,6 +121,16 @@ var WalletKitClient = class {
   async getNonce() {
     return this.#request("POST", "/v1/auth/nonce");
   }
+  /**
+   * Mint a short-lived (~120s) HS256 token for the IPFS upload service
+   * (`POST /v1/ipfs/upload-token`, authenticated). Fetch one per upload:
+   * the token is meant to expire within the service's 600s window (which the
+   * service does not enforce today — see the relayer's routes/ipfs.ts). 503
+   * when the relayer has no upload secret configured.
+   */
+  async getIpfsUploadToken() {
+    return this.#request("POST", "/v1/ipfs/upload-token");
+  }
   async importProfile(input) {
     return this.#request("POST", "/v1/profiles/import", input);
   }
@@ -160,6 +170,60 @@ var WalletKitClient = class {
   async getSubscription() {
     return this.#request("GET", "/v1/billing/subscription");
   }
+  /**
+   * What can be bought, per store — what a store page renders. With `store`
+   * the list holds only the plans purchasable there plus the free tier;
+   * without it every active plan comes back with its Stripe products (empty
+   * = not purchasable yet). The layout is the caller's: group by `kind` /
+   * `interval`; Stripe products arrive in `sortOrder`.
+   */
+  async getCatalog(opts) {
+    const query = new URLSearchParams();
+    if (opts?.audience) query.set("audience", opts.audience);
+    if (opts?.store) query.set("store", opts.store);
+    const qs = query.toString();
+    return this.#request("GET", `/v1/billing/catalog${qs ? `?${qs}` : ""}`);
+  }
+  /**
+   * Every subscription of the caller's account, live ones first — what the
+   * dashboard's account / subscription dropdown renders.
+   */
+  async listSubscriptions() {
+    return this.#request("GET", "/v1/subscriptions");
+  }
+  /**
+   * Hand a StoreKit 2 purchase to the relayer (DEV-16570): pass the
+   * transaction's `jwsRepresentation` after a purchase and for every
+   * `Transaction.updates` entry. Purchase with `appAccountToken` = the
+   * caller's `accountId` from {@link RelayerClient.me}; a transaction bought
+   * for another account rejects with `403 app_account_token_mismatch`, one
+   * attached to another account with `409 held_by_another_account` — restore
+   * those with {@link RelayerClient.claimSubscription}. `422 unmapped_product`
+   * = the product id is not in the catalog.
+   */
+  async submitAppleTransaction(signedTransaction) {
+    return this.#request("POST", "/v1/billing/apple/transactions", {
+      signedTransaction
+    });
+  }
+  /**
+   * Restore purchases: move a store subscription onto the caller's account
+   * (single owner — the previous account loses it). Pass a signed transaction
+   * from `Transaction.currentEntitlements`; only a device signed in with the
+   * purchasing Apple ID can produce one. A subscription moves to a different
+   * account at most once per calendar month: `409 claim_cooldown` otherwise.
+   */
+  async claimSubscription(input) {
+    return this.#request("POST", "/v1/subscriptions/claim", input);
+  }
+  /**
+   * Stripe Customer Portal URL for the caller's own Stripe subscription.
+   * Rejects with `manage_in_store` (409) for an Apple / Google subscription
+   * and `no_subscription` (404) when there is nothing to manage.
+   */
+  async createPortalSession(opts) {
+    return this.#request("POST", "/v1/billing/portal-session", opts ?? {});
+  }
   /**
    * Start a Stripe Checkout for a tier and return the created session
    * `{ id, url }`. In a browser this ALSO navigates to `url` by default

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@universal-everything/sdk-core",
-  "version": "1.1.0",
+  "version": "1.2.0-dev.0a281f1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/universal-everything/universal-relayer.git",