@sogni-ai/sogni-client 5.0.0 → 5.1.0-alpha.10

package/CHANGELOG.md

@@ -1,3 +1,99 @@
+# [5.1.0-alpha.10](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.9...v5.1.0-alpha.10) (2026-06-18)
+
+
+### Features
+
+* **audio:** prefer ACE-Step XL music models ([ec5a715](https://github.com/Sogni-AI/sogni-client/commit/ec5a71579d04b42863ce9627c8ea4935b0190f70))
+* **projects:** expose LTX-2.3 v2v outpaint and inpaint controls ([1a60576](https://github.com/Sogni-AI/sogni-client/commit/1a605766e42b6fa5cdedf0a64425deb51cbf81b1))
+
+# [5.1.0-alpha.9](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.8...v5.1.0-alpha.9) (2026-06-16)
+
+
+### Features
+
+* **subscription:** expose frontier vendor discount in types ([1e06f99](https://github.com/Sogni-AI/sogni-client/commit/1e06f99e54e39c2d09d65263c0ed6a5f52dbac18))
+
+# [5.1.0-alpha.8](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.7...v5.1.0-alpha.8) (2026-06-16)
+
+
+### Features
+
+* **chat:** carry subscription-limit fields on ChatJobError ([33c7ecd](https://github.com/Sogni-AI/sogni-client/commit/33c7ecdab22c571f6983fbb479bdbb5eb885a672))
+* **chat:** forward 4081 limit fields at error call sites ([ef5b66a](https://github.com/Sogni-AI/sogni-client/commit/ef5b66a8b28dd52755f22cf76609258ecf2fe6dc))
+* **projects:** surface 4081 limit fields on render errors ([13fa158](https://github.com/Sogni-AI/sogni-client/commit/13fa158f00c4e4415bb4d0f3c7eaf9979f1f7d40))
+* **socket:** type 4081 limit fields on job error events ([0026438](https://github.com/Sogni-AI/sogni-client/commit/0026438ccbfb1cefe5be38861372d1430ade0eb2))
+* **subscription:** add isSubscriptionLimitError helper ([139953b](https://github.com/Sogni-AI/sogni-client/commit/139953bc003aefc2f3ba09f8e4000982a071f7e8))
+* **subscription:** recognize 4081 feature-gate denial code ([c513fe6](https://github.com/Sogni-AI/sogni-client/commit/c513fe67243c91e0ca8ccb5d301a3be20dcf1486))
+
+# [5.1.0-alpha.7](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.6...v5.1.0-alpha.7) (2026-06-12)
+
+
+### Bug Fixes
+
+* **account:** map real socket entitlement status domain without dropping fields ([c2e7499](https://github.com/Sogni-AI/sogni-client/commit/c2e7499c5d254e8ce61da257b44307bca97ea56c))
+
+
+### Features
+
+* **account:** accept chat checkout redirect target ([3900336](https://github.com/Sogni-AI/sogni-client/commit/390033692aaa46eff521030d80ba712f15bd3302))
+* **account:** guard subscription writes against stale transports ([c60af1f](https://github.com/Sogni-AI/sogni-client/commit/c60af1ff4e4a9a8af1a8e2393899026f176a3f53))
+* **chat:** preserve job error codes via typed ChatJobError ([dd5ad1d](https://github.com/Sogni-AI/sogni-client/commit/dd5ad1d585c709382547bfa4cff2aa98d734414c))
+* **chat:** serialize billingMode on all three chat transports ([787dd43](https://github.com/Sogni-AI/sogni-client/commit/787dd4391dee1735a6d3d3a7953f25ec6c722a4d))
+* **types:** export subscription billing socket error-code constants ([2fd5af4](https://github.com/Sogni-AI/sogni-client/commit/2fd5af49ffa76d6f1a304c6a06577468f5865c2e))
+
+# [5.1.0-alpha.6](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.5...v5.1.0-alpha.6) (2026-06-12)
+
+
+### Features
+
+* sync socket subscription entitlement ([fa5d24d](https://github.com/Sogni-AI/sogni-client/commit/fa5d24d307992993ac312c3b1e8ab94277529aa4))
+
+# [5.1.0-alpha.5](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.4...v5.1.0-alpha.5) (2026-06-11)
+
+
+### Features
+
+* **subscription:** pending plan-change snapshot fields and grace-period doc fix ([596e4a0](https://github.com/Sogni-AI/sogni-client/commit/596e4a030dc1114e5fdd90d3dce3dd799c5f1ede))
+
+# [5.1.0-alpha.4](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.3...v5.1.0-alpha.4) (2026-06-11)
+
+
+### Bug Fixes
+
+* **projects:** forward billing mode metadata ([975fdb0](https://github.com/Sogni-AI/sogni-client/commit/975fdb09adcbd74c11fa6786edb6f1d2392583eb))
+
+# [5.1.0-alpha.3](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.2...v5.1.0-alpha.3) (2026-06-10)
+
+
+### Features
+
+* **subscription:** mirror term, google productId, and manual provider ([78b3114](https://github.com/Sogni-AI/sogni-client/commit/78b311457c71448578b8f561cc7865e7bcaf9f20))
+
+# [5.1.0-alpha.2](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.1...v5.1.0-alpha.2) (2026-06-10)
+
+
+### Bug Fixes
+
+* **account:** correct trial usage SDK surface and eligibility reason docs ([222252d](https://github.com/Sogni-AI/sogni-client/commit/222252d87305f72b0be71f23b26a6607ad25bf46))
+
+
+### Features
+
+* **account:** add trial eligibility, device-id, and startTrial checkout ([6564c82](https://github.com/Sogni-AI/sogni-client/commit/6564c8225aec37245a4c4a051119a48da6fc14a5))
+
+# [5.1.0-alpha.1](https://github.com/Sogni-AI/sogni-client/compare/v5.0.0...v5.1.0-alpha.1) (2026-06-05)
+
+
+### Bug Fixes
+
+* **subscription:** accept unlimited_pro tier in isUnlimited getter ([dd60513](https://github.com/Sogni-AI/sogni-client/commit/dd60513650071a46a2e43f7d81bae96026c4af93))
+* **subscription:** align entitlement SDK surface ([df2b752](https://github.com/Sogni-AI/sogni-client/commit/df2b7527f479778f073ac8f05b39912e84874666))
+
+
+### Features
+
+* **account:** add subscription entitlement accessors ([22682c4](https://github.com/Sogni-AI/sogni-client/commit/22682c4ac8a970b4189ec94ea9f7bc3fa215533e))
+
 # [5.0.0](https://github.com/Sogni-AI/sogni-client/compare/v4.1.1...v5.0.0) (2026-05-29)
 
 

package/README.md

@@ -176,6 +176,48 @@ sogni.client.on('disconnected', ({ code, reason }) => {
 });
 ```
 
+### Subscription entitlements
+
+The account API exposes the public subscription plan catalog and the current wallet's entitlement snapshot:
+
+```typescript
+const plans = await sogni.account.getSubscriptionPlans();
+
+const subscription = await sogni.account.refreshSubscription();
+if (sogni.account.currentAccount.isUnlimited) {
+  console.log('Unlimited tier:', subscription.tier);
+}
+```
+
+`currentAccount.isUnlimited` is `true` when the latest entitlement snapshot has `active: true` and `tier` is either `unlimited` or `unlimited_pro`. The server keeps `active` true for entitled states until access actually ends: trials and cancel-at-period-end windows remain entitled, with `currentPeriodEnd` reflecting the paid-through date. Canceling during a free trial is the exception: it ends Unlimited access immediately by default, so the next snapshot reports `active: false`. A `grace_period` snapshot is never entitled and returns `active: false`: it means the provider (Apple billing grace / Google Play grace / Stripe retries) is retrying the renewal payment, and unlimited render access is paused while the retry is in progress — render submissions under the plan return a specific error from the platform explaining that the renewal payment is being retried and that unlimited access resumes once it succeeds. Renders can still be paid with Spark/SOGNI in the meantime, and unlimited access resumes automatically when the renewal succeeds. During grace the snapshot's effective period end indicates the payment-retry window, not access. Period dates are ISO timestamp strings.
+
+A canceled-but-still-paid subscription carries `cancelAtPeriodEnd: true` and keeps access until `currentPeriodEnd`. When a downgrade or plan switch is scheduled for the next renewal, the snapshot may also carry `scheduledTier`, `scheduledTerm`, and `scheduledChangeAt` (ISO timestamp) — absent when no change is pending — so UIs can render "Your plan will change to X on date" messaging while the current tier keeps its benefits.
+
+When a job is explicitly submitted with `billingMode: 'subscription'` and the subscription cannot cover it, the platform rejects the job with a subscription-specific error code, exported as `SUBSCRIPTION_ERROR_CODES` from the package root:
+
+- `4078` (`NOT_ENTITLED`) — no active subscription entitlement covers the job.
+- `4079` (`QUEUE_CAP`) — the subscription's concurrent job queue cap was reached.
+- `4080` (`GRACE_RETRY`) — the subscription is in its billing-grace window: the renewal payment is being retried and unlimited access is paused until it succeeds. On `4080`, offer the user a "pay with Spark/SOGNI" fallback (token billing) instead of auto-retrying the subscription job in a loop — it will keep failing until the renewal succeeds.
+
+`billingMode` (`'auto' | 'subscription' | 'tokens'`, exported as `BillingMode`) is accepted by project params and by all three chat transports: `sogni.chat.completions.create()` (socket), `sogni.chat.hosted.create()` (REST `/v1/chat/completions`), and `sogni.chat.runs.create()` (durable runs, where it serializes as `billing_mode`).
+
+Chat job failures preserve this error contract. Streamed and non-streaming chat completions, hosted REST chat, and durable chat runs fail with a `ChatJobError` (exported from the package root): `.message` stays the human-readable server message, while `code`/`errorCode` carry the wire code string (e.g. `'4080'`), `errorType` carries the server's tag (e.g. `'subscription_unavailable'`), and the `subscriptionErrorCode` getter maps the code back to the numeric `SUBSCRIPTION_ERROR_CODES` value when applicable — so apps can branch without string-matching.
+
+Unlimited fair-use accounting and enforcement are handled dynamically by the Sogni socket service. The SDK does not expose per-period usage counters or plan limit tables for clients to store or display as durable user-facing limits.
+
+To start Stripe checkout, use a plan's `planId` (`unlimited` or `unlimited_pro`) and `term` (`monthly` or `annual`). Checkout and portal sessions require user authentication; API-key auth is rejected for those browser redirect operations.
+
+```typescript
+const { url } = await sogni.account.createSubscriptionCheckout('unlimited_pro', 'annual', {
+  redirectType: 'web',
+  appSource: 'my-integration'
+});
+window.location.href = url;
+
+const portal = await sogni.account.createSubscriptionPortalSession();
+window.location.href = portal.url;
+```
+
 ## Image Generation
 
 Sogni supports a wide range of models for image generation. You can find a list of available models in

package/dist/Account/CurrentAccount.d.ts

@@ -1,5 +1,6 @@
 import DataEntity from '../lib/DataEntity.js';
 import { Balances } from './types.js';
+import { SubscriptionEntitlementSnapshot } from './subscription.types.js';
 import { SupernetType } from '../ApiClient/WebSocketClient/types.js';
 /**
  * @inline
@@ -20,6 +21,17 @@ export interface AccountData {
     walletAddress?: string;
     username?: string;
     email?: string;
+    /**
+     * The most recently fetched subscription entitlement snapshot.
+     * `undefined` until the account receives a socket entitlement snapshot or
+     * {@link AccountApi.getSubscriptionStatus} / {@link AccountApi.refreshSubscription}
+     * has been called.
+     *
+     * Subscribe to the `'updated'` event (inherited from `DataEntity`) to react
+     * to changes; the `changedKeys` array will include `'subscription'` when
+     * this field is refreshed.
+     */
+    subscription?: SubscriptionEntitlementSnapshot;
 }
 /**
  * Current account data.
@@ -35,5 +47,23 @@ declare class CurrentAccount extends DataEntity<AccountData> {
     get walletAddress(): string | undefined;
     get username(): string | undefined;
     get email(): string | undefined;
+    /**
+     * The most recently cached subscription entitlement snapshot.
+     * `undefined` until the account receives a socket entitlement snapshot or
+     * {@link AccountApi.getSubscriptionStatus} / {@link AccountApi.refreshSubscription}
+     * has been called.
+     */
+    get subscription(): SubscriptionEntitlementSnapshot | undefined;
+    /**
+     * Convenience getter - `true` when the account has an effective
+     * subscription entitlement on any Unlimited tier (`"unlimited"` or
+     * `"unlimited_pro"`).
+     *
+     * Returns `false` when no entitlement snapshot has been fetched yet, when
+     * the server reports no active entitlement, or when the tier is not an
+     * Unlimited tier. Call {@link AccountApi.refreshSubscription} to force a REST
+     * refresh when no socket entitlement snapshot has been received yet.
+     */
+    get isUnlimited(): boolean;
 }
 export default CurrentAccount;

package/dist/Account/CurrentAccount.js

@@ -24,7 +24,8 @@ function getDefaults() {
             }
         },
         walletAddress: undefined,
-        username: undefined
+        username: undefined,
+        subscription: undefined
     };
 }
 /**
@@ -59,6 +60,31 @@ class CurrentAccount extends DataEntity_js_1.default {
     get email() {
         return this.data.email;
     }
+    /**
+     * The most recently cached subscription entitlement snapshot.
+     * `undefined` until the account receives a socket entitlement snapshot or
+     * {@link AccountApi.getSubscriptionStatus} / {@link AccountApi.refreshSubscription}
+     * has been called.
+     */
+    get subscription() {
+        return this.data.subscription;
+    }
+    /**
+     * Convenience getter - `true` when the account has an effective
+     * subscription entitlement on any Unlimited tier (`"unlimited"` or
+     * `"unlimited_pro"`).
+     *
+     * Returns `false` when no entitlement snapshot has been fetched yet, when
+     * the server reports no active entitlement, or when the tier is not an
+     * Unlimited tier. Call {@link AccountApi.refreshSubscription} to force a REST
+     * refresh when no socket entitlement snapshot has been received yet.
+     */
+    get isUnlimited() {
+        const sub = this.data.subscription;
+        if (!sub || !sub.active)
+            return false;
+        return sub.tier === 'unlimited' || sub.tier === 'unlimited_pro';
+    }
 }
 exports.default = CurrentAccount;
 //# sourceMappingURL=CurrentAccount.js.map

package/dist/Account/CurrentAccount.js.map

@@ -1 +1 @@
-{"version":3,"file":"CurrentAccount.js","sourceRoot":"","sources":["../../src/Account/CurrentAccount.ts"],"names":[],"mappings":";;;;;AAAA,yEAA8C;AAwB9C,SAAS,WAAW;IAClB,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,OAAO,EAAE,IAAI;QACb,OAAO,EAAE;YACP,KAAK,EAAE;gBACL,MAAM,EAAE,GAAG;gBACX,KAAK,EAAE,GAAG;gBACV,GAAG,EAAE,GAAG;gBACR,OAAO,EAAE,GAAG;aACb;YACD,KAAK,EAAE;gBACL,MAAM,EAAE,GAAG;gBACX,KAAK,EAAE,GAAG;gBACV,GAAG,EAAE,GAAG;gBACR,OAAO,EAAE,GAAG;gBACZ,aAAa,EAAE,GAAG;aACnB;SACF;QACD,aAAa,EAAE,SAAS;QACxB,QAAQ,EAAE,SAAS;KACpB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,cAAe,SAAQ,uBAAuB;IAClD,YAAY,IAAkB;QAC5B,KAAK,CAAC,IAAI,IAAI,WAAW,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI,cAAc;QAChB,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACnC,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACjC,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;IAC3B,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;IAC3B,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACjC,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;IAC5B,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;IACzB,CAAC;CACF;AAED,kBAAe,cAAc,CAAC"}
+{"version":3,"file":"CurrentAccount.js","sourceRoot":"","sources":["../../src/Account/CurrentAccount.ts"],"names":[],"mappings":";;;;;AAAA,yEAA8C;AAoC9C,SAAS,WAAW;IAClB,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,OAAO,EAAE,IAAI;QACb,OAAO,EAAE;YACP,KAAK,EAAE;gBACL,MAAM,EAAE,GAAG;gBACX,KAAK,EAAE,GAAG;gBACV,GAAG,EAAE,GAAG;gBACR,OAAO,EAAE,GAAG;aACb;YACD,KAAK,EAAE;gBACL,MAAM,EAAE,GAAG;gBACX,KAAK,EAAE,GAAG;gBACV,GAAG,EAAE,GAAG;gBACR,OAAO,EAAE,GAAG;gBACZ,aAAa,EAAE,GAAG;aACnB;SACF;QACD,aAAa,EAAE,SAAS;QACxB,QAAQ,EAAE,SAAS;QACnB,YAAY,EAAE,SAAS;KACxB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,cAAe,SAAQ,uBAAuB;IAClD,YAAY,IAAkB;QAC5B,KAAK,CAAC,IAAI,IAAI,WAAW,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI,cAAc;QAChB,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACnC,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACjC,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;IAC3B,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;IAC3B,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACjC,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;IAC5B,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;IACzB,CAAC;IAED;;;;;OAKG;IACH,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC;IAChC,CAAC;IAED;;;;;;;;;OASG;IACH,IAAI,WAAW;QACb,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC;QACnC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QACtC,OAAO,GAAG,CAAC,IAAI,KAAK,WAAW,IAAI,GAAG,CAAC,IAAI,KAAK,eAAe,CAAC;IAClE,CAAC;CACF;AAED,kBAAe,cAAc,CAAC"}

package/dist/Account/index.d.ts

@@ -1,4 +1,5 @@
 import { AccountCreateData, AccountCreateParams, Balances, ClaimOptions, FullBalances, LoginData, MeData, Reward, RewardsQuery, TxHistoryEntry, TxHistoryParams } from './types.js';
+import { CreateSubscriptionCheckoutOptions, SubscriptionCheckoutResult, SubscriptionEntitlementSnapshot, SubscriptionPlanId, SubscriptionPlan, SubscriptionPortalSession, SubscriptionTerm, SubscriptionUsage, TrialEligibility } from './subscription.types.js';
 import ApiGroup, { ApiConfig } from '../ApiGroup.js';
 import { Wallet } from 'ethers';
 import { ApiResponse } from '../ApiClient/index.js';
@@ -17,12 +18,44 @@ import { SupernetType } from '../ApiClient/WebSocketClient/types.js';
  */
 declare class AccountApi extends ApiGroup {
     readonly currentAccount: CurrentAccount;
+    /**
+     * Highest entitlement `version` applied to `currentAccount.subscription`.
+     * Socket payloads carry a monotonically increasing version; writes that
+     * carry an older version than the one already applied are discarded instead
+     * of overwriting fresher data.
+     */
+    private lastAppliedSubscriptionVersion;
+    /**
+     * Logical clock counting applied socket entitlement writes. A REST refresh
+     * captures this counter before its request goes on the wire; if it advanced
+     * by the time the response arrives, a fresher socket push landed mid-flight
+     * and the REST snapshot is discarded as stale.
+     */
+    private appliedSubscriptionSocketWrites;
     constructor(config: ApiConfig);
     private handleBalanceUpdate;
     private handleChangeNetwork;
     private handleServerConnected;
     private handleServerConnecting;
     private handleServerDisconnected;
+    private mapSocketSubscriptionEntitlement;
+    /**
+     * Single chokepoint through which every subscription entitlement writer
+     * (REST refresh, socket entitlement push, socket authenticated seeding)
+     * must route.
+     *
+     * Guards against last-writer-wins races between the two transports: writes
+     * carrying an older `version` than the one already applied are discarded,
+     * and an unversioned REST snapshot whose request started before a socket
+     * push was applied is discarded as stale. Snapshots deep-equal to the
+     * current one are accepted without re-applying, so reconnect re-seeds and
+     * tab replays do not emit redundant 'updated' events.
+     *
+     * @returns `true` when the snapshot was accepted (even if identical to the
+     * current one), `false` when it was discarded as stale.
+     */
+    private applySubscriptionSnapshot;
+    private handleSubscriptionEntitlementUpdated;
     private handleSocketAuthenticated;
     private handleAuthUpdated;
     /**
@@ -212,5 +245,143 @@ declare class AccountApi extends ApiGroup {
      * @param provider - Provider name, defaults to 'base', can be 'base', 'etherlink', etc.
      */
     approveTokenUsage(password: string, spender: 'account' | 'staker', provider?: string): Promise<void>;
+    /**
+     * Fetch the current user's subscription entitlement snapshot.
+     *
+     * Returns an object describing whether the account has an effective
+     * subscription entitlement, the tier, period boundaries, usage, limits, and
+     * enabled capabilities. When no subscription exists, `active` is `false` and
+     * `status` is `'none'`.
+     *
+     * Also updates `currentAccount.subscription` so callers can read the
+     * snapshot from the observable entity without re-fetching.
+     *
+     * @example
+     * ```typescript
+     * const snap = await sogni.account.getSubscriptionStatus();
+     * if (snap.active) {
+     *   console.log('Plan:', snap.tier, 'until', snap.currentPeriodEnd);
+     * }
+     * ```
+     */
+    getSubscriptionStatus(): Promise<SubscriptionEntitlementSnapshot>;
+    /**
+     * Fetch the current user's usage for the active billing cycle.
+     *
+     * Returns the render/job counters for the subscriber's current billing cycle
+     * (not a calendar month). While the entitlement is `'trialing'`, the response
+     * also carries `trialEndsAt`, `trialCreditsLimit`, and `trialCreditsUsed` so
+     * you can render "X of N trial credits used" messaging; those fields are
+     * omitted for non-trial subscriptions.
+     *
+     * Note: these trial usage fields come from this endpoint, NOT from
+     * {@link getSubscriptionStatus} — the entitlement snapshot never carries
+     * trial usage.
+     *
+     * @example
+     * ```typescript
+     * const usage = await sogni.account.getSubscriptionUsage();
+     * if (usage.trialCreditsLimit !== undefined) {
+     *   console.log(`${usage.trialCreditsUsed} of ${usage.trialCreditsLimit} trial credits used`);
+     * }
+     * ```
+     */
+    getSubscriptionUsage(): Promise<SubscriptionUsage>;
+    /**
+     * Check whether the current account is eligible to start a free trial.
+     *
+     * Returns `{ eligible, reasonCode }`. `reasonCode` is ALWAYS present: it is
+     * `'eligible'` when a trial may be started, or a deny reason otherwise (e.g.
+     * `'wallet_already_used'`, `'strong_signal_match'`, `'weak_combo'`). Use this
+     * before offering a "start free trial" flow.
+     *
+     * @example
+     * ```typescript
+     * const { eligible, reasonCode } = await sogni.account.getTrialEligibility();
+     * if (eligible) {
+     *   const { url } = await sogni.account.createSubscriptionCheckout('unlimited', 'monthly', {
+     *     startTrial: true
+     *   });
+     * }
+     * ```
+     */
+    getTrialEligibility(): Promise<TrialEligibility>;
+    /**
+     * Persist a raw persistent device identifier for the current account.
+     *
+     * Used for free-trial anti-abuse attribution so the server can detect device
+     * reuse across accounts. Requires an authenticated session.
+     *
+     * @param deviceId - Raw persistent device identifier.
+     *
+     * @example
+     * ```typescript
+     * await sogni.account.setDeviceId(myPersistentDeviceId);
+     * ```
+     */
+    setDeviceId(deviceId: string): Promise<void>;
+    /**
+     * Fetch the list of available subscription plans.
+     *
+     * This is a public endpoint; no authentication is required.
+     *
+     * @example
+     * ```typescript
+     * const plans = await sogni.account.getSubscriptionPlans();
+     * plans.forEach(p => console.log(p.displayName, p.priceUsd));
+     * ```
+     */
+    getSubscriptionPlans(): Promise<SubscriptionPlan[]>;
+    /**
+     * Create a Stripe checkout session to subscribe to a plan.
+     *
+     * Returns a `url` to which the user should be redirected to complete payment.
+     * After a successful checkout Stripe will redirect back to your configured
+     * return URL and the subscription entitlement will become active.
+     *
+     * Pass `options.startTrial` to control free-trial behavior: `true` starts a
+     * trial when the account is eligible, while `false` is sent verbatim to
+     * subscribe immediately with no trial even if the account is eligible.
+     * Pass `options.deviceId` to forward a raw persistent device identifier for
+     * trial anti-abuse attribution.
+     *
+     * @param planId - The plan identifier from {@link getSubscriptionPlans}
+     * @param term   - Billing cadence: `'monthly'` or `'annual'`
+     * @param options - Optional checkout metadata, redirect target, and trial controls.
+     *
+     * @example
+     * ```typescript
+     * const { url } = await sogni.account.createSubscriptionCheckout('unlimited', 'monthly');
+     * window.location.href = url;
+     * ```
+     */
+    createSubscriptionCheckout(planId: SubscriptionPlanId, term: SubscriptionTerm, options?: CreateSubscriptionCheckoutOptions): Promise<SubscriptionCheckoutResult>;
+    /**
+     * Create a Stripe customer portal session for managing an existing subscription.
+     *
+     * Returns a `url` to which the user should be redirected. The portal lets
+     * them update payment methods, cancel, or view invoices.
+     *
+     * @example
+     * ```typescript
+     * const { url } = await sogni.account.createSubscriptionPortalSession();
+     * window.location.href = url;
+     * ```
+     */
+    createSubscriptionPortalSession(): Promise<SubscriptionPortalSession>;
+    /**
+     * Refresh the cached subscription entitlement on `currentAccount`.
+     *
+     * Convenience wrapper around {@link getSubscriptionStatus} that makes the
+     * intent ("I want to pull fresh entitlement data into the observable
+     * account entity") explicit at the call site.
+     *
+     * @example
+     * ```typescript
+     * await sogni.account.refreshSubscription();
+     * console.log(sogni.account.currentAccount.isUnlimited);
+     * ```
+     */
+    refreshSubscription(): Promise<SubscriptionEntitlementSnapshot>;
 }
 export default AccountApi;