@oxy.so/core 4.4.0 → 4.5.0-oxy-one.1

package/dist/cjs/api/assets.js

@@ -38,6 +38,12 @@ const ASSET_URL_CACHE_LIFETIME_FRACTION = 0.5;
 /** Assumed URL lifetime (seconds) when no `expiresIn` is asked for; the API default. */
 const DEFAULT_ASSET_URL_EXPIRES_IN_SECONDS = 3600;
 const ASSET_TTL = 5 * 60 * 1000;
+/**
+ * Default bound on one `POST /assets/upload`, in ms. The client's per-request
+ * default (5s) is sized for JSON calls; a video sent over a phone connection
+ * needs minutes, and timing it out at 5s failed every upload past a few MB.
+ */
+const ASSET_UPLOAD_TIMEOUT_MS = 10 * 60 * 1000;
 /**
  * How long a resolved asset URL may stay in the SDK's GET cache, in ms: never
  * longer than the media token's lifetime, and discounted below it.
@@ -51,6 +57,24 @@ class AssetsApi {
     constructor(ctx) {
         this.ctx = ctx;
     }
+    /** Upload already-admitted bytes. Sends required bucket headers, never an Oxy bearer. */
+    async putPresignedUpload(init, body) {
+        if (!init.uploadUrl)
+            return; // bytes already exist for this account
+        const target = new URL(init.uploadUrl);
+        if (target.protocol !== 'https:')
+            throw new Error('Presigned uploads require HTTPS');
+        const headers = new Headers(init.requiredHeaders);
+        headers.forEach((_value, name) => {
+            if (!['if-none-match', 'content-type', 'x-amz-checksum-sha256', 'cache-control'].includes(name.toLowerCase()))
+                throw new Error('Unsupported required upload header');
+        });
+        if (body.type && !headers.has('Content-Type'))
+            headers.set('Content-Type', body.type);
+        const result = await fetch(target.toString(), { method: 'PUT', body, headers, credentials: 'omit', redirect: 'error' });
+        if (!result.ok)
+            throw new Error(`Presigned upload failed (${result.status})`);
+    }
     // ── Upload ───────────────────────────────────────────────────────────────
     /**
      * Upload a file. Accepts a web `File`/`Blob` or a React Native
@@ -96,7 +120,10 @@ class AssetsApi {
         if (options.metadata)
             formData.append('metadata', JSON.stringify(options.metadata));
         try {
-            const response = await this.ctx.request('POST', '/assets/upload', formData, { cache: false });
+            const response = await this.ctx.request('POST', '/assets/upload', formData, {
+                cache: false,
+                timeout: options.timeout ?? ASSET_UPLOAD_TIMEOUT_MS,
+            });
             options.onProgress?.(100);
             return response;
         }

package/dist/cjs/api/auth.js

@@ -714,14 +714,19 @@ class AuthApi {
         this.agent = new AuthAgentApi(ctx);
     }
     /**
-     * Register a new identity with public key authentication
-     * Identity is purely cryptographic - username and profile data are optional
+     * Register a new account for a public key, together with its username.
+     *
+     * The username is required: the server writes it in the same insert as the
+     * key, so an account never exists without one. A taken username is a 409
+     * (`Username already taken`), as is a key that is already registered
+     * (`Identity already registered`).
      *
      * @param publicKey - The user's ECDSA public key (hex)
      * @param signature - Signature of the registration request
      * @param timestamp - Timestamp when the signature was created
+     * @param username - The account's username
      */
-    async registerKey(publicKey, signature, timestamp) {
+    async registerKey(publicKey, signature, timestamp, username) {
         // Advisory for now (server soft-enforces — see
         // `SessionController.register`), but solved unconditionally so every
         // client is already sending it once the server starts requiring it.
@@ -731,6 +736,7 @@ class AuthApi {
             publicKey,
             signature,
             timestamp,
+            username,
             powNonce,
         }, { cache: false, skipAuth: true });
         if (!res || (typeof res === 'object' && Object.keys(res).length === 0)) {

package/dist/cjs/api/billing.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BillingApi = void 0;
+const contracts_1 = require("@oxy.so/contracts");
 /**
  * `oxy.billing` — the signed-in user's subscription, wallet and payment history.
  *
@@ -12,35 +13,43 @@ exports.BillingApi = void 0;
  * `payment.controller`, `wallet.routes` in `packages/api`); `Date` columns
  * arrive as ISO-8601 strings.
  */
-const contracts_1 = require("@oxy.so/contracts");
 const contracts_2 = require("@oxy.so/contracts");
+const contracts_3 = require("@oxy.so/contracts");
+const contracts_4 = require("@oxy.so/contracts");
 const SUBSCRIPTION_TTL = 2 * 60 * 1000;
 const WALLET_TTL = 60 * 1000;
 class BillingApi {
     constructor(ctx) {
         this.ctx = ctx;
     }
+    async startPersonalPlanCheckout(request) {
+        return contracts_1.personalPlanCheckoutResultSchema.parse(await this.ctx.request('POST', '/billing/checkout/personal-plan', contracts_1.personalPlanCheckoutRequestSchema.parse(request), { cache: false }));
+    }
+    /** Public versioned personal plans. Discovery never proves customer access. */
+    async personalPlans() {
+        return contracts_2.personalPlanCatalogueSchema.parse(await this.ctx.request('GET', '/billing/personal-plans', undefined, { cache: false }));
+    }
     /** Product rights only; requires a production application-bound user session. Never cached. */
     async productAccess(query) {
-        const parsed = contracts_1.subjectProductAccessQuerySchema.parse(query);
+        const parsed = contracts_3.subjectProductAccessQuerySchema.parse(query);
         const response = await this.ctx.request('GET', `/v1/products/${encodeURIComponent(parsed.productId)}/access/${encodeURIComponent(parsed.subjectAccountId)}`, undefined, { cache: false });
-        return contracts_1.subjectProductAccessSchema.parse(response);
+        return contracts_3.subjectProductAccessSchema.parse(response);
     }
     /** Named commercial sources for the current subject; no inferred plan collapse. */
-    async productSubscriptions() {
-        return contracts_2.productSubscriptionsResponseSchema.parse(await this.ctx.request("GET", "/billing/product-subscriptions", undefined, { cache: false })).subscriptions;
+    async productSubscriptions(expectedSubjectAccountId) {
+        return contracts_4.productSubscriptionsResponseSchema.parse(await this.ctx.request("GET", expectedSubjectAccountId ? `/billing/product-subscriptions?expectedSubjectAccountId=${encodeURIComponent(expectedSubjectAccountId)}` : "/billing/product-subscriptions", undefined, { cache: false })).subscriptions;
     }
     /** Per-grant credit provenance; no interpretation of the historical mixed balance. */
     async creditGrants() {
-        return contracts_2.subscriptionCreditGrantsResponseSchema.parse(await this.ctx.request("GET", "/billing/credit-grants", undefined, { cache: false })).grants;
+        return contracts_4.subscriptionCreditGrantsResponseSchema.parse(await this.ctx.request("GET", "/billing/credit-grants", undefined, { cache: false })).grants;
     }
     /** Payer-only named-source cancellation. Resolves on provider acceptance, including pending local reconciliation. Use cancelProductSubscriptionWithStatus for detailed completion state. */
-    async cancelProductSubscription(sourceId, expectedSubjectAccountId) {
-        await this.ctx.request("POST", "/billing/product-subscriptions/cancel", contracts_2.cancelProductSubscriptionSchema.parse({ sourceId, ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }), { cache: false });
+    async cancelProductSubscription(sourceId, expectedSubjectAccountId, actionId) {
+        await this.ctx.request("POST", "/billing/product-subscriptions/cancel", contracts_4.cancelProductSubscriptionSchema.parse({ sourceId, ...(actionId ? { actionId } : {}), ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }), { cache: false });
     }
     /** Provider acceptance versus completed local cancellation, for user-facing flows. */
-    async cancelProductSubscriptionWithStatus(sourceId, expectedSubjectAccountId) {
-        return contracts_2.productSubscriptionCancellationResultSchema.parse(await this.ctx.request('POST', '/billing/product-subscriptions/cancel', contracts_2.cancelProductSubscriptionSchema.parse({ sourceId, ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }), { cache: false }));
+    async cancelProductSubscriptionWithStatus(sourceId, expectedSubjectAccountId, actionId) {
+        return contracts_4.productSubscriptionCancellationResultSchema.parse(await this.ctx.request('POST', '/billing/product-subscriptions/cancel', contracts_4.cancelProductSubscriptionSchema.parse({ sourceId, ...(actionId ? { actionId } : {}), ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }), { cache: false }));
     }
     /** The signed-in user's payment history. Never cached. */
     async payments() {

package/dist/cjs/api/users.js

@@ -109,8 +109,8 @@ class UsersApi {
         return settled.flat();
     }
     /** The signed-in user. Cached 1 minute. */
-    async me() {
-        const user = await this.ctx.request('GET', '/users/me', undefined, { cache: true, cacheTTL: ME_TTL });
+    async me(options) {
+        const user = await this.ctx.request('GET', '/users/me', undefined, { cache: options?.cache ?? true, cacheTTL: ME_TTL });
         return (0, userIdentity_1.normalizeUserIdentity)(user);
     }
     /** A profile by username. Cached 5 minutes; `{ cache: false }` as in `get`. */

package/dist/cjs/server/OxyServer.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OxyServer = exports.ServiceCredentialMismatchError = exports.ANONYMOUS_SERVICE_TOKEN_RETRY_MS = void 0;
+const contracts_1 = require("@oxy.so/contracts");
 /**
  * `OxyServer` — the Oxy client for a backend.
  *
@@ -279,6 +280,26 @@ class OxyServer extends OxyServices_1.OxyServices {
      * request is on behalf of that user (the API checks the delegation grant).
      * Never cached unless `cache` says so. Rejects with `OxyApiError`.
      */
+    /** Validated request's user session only; never changes the shared client's token. */
+    async productGrantSnapshotForUser(query, accessToken) {
+        const parsed = contracts_1.subjectProductAccessQuerySchema.parse(query);
+        if (!accessToken || /[\r\n]/.test(accessToken))
+            throw new Error('A user session is required');
+        const answer = await this.request('GET', `/v1/products/${encodeURIComponent(parsed.productId)}/access/${encodeURIComponent(parsed.subjectAccountId)}/grants`, undefined, { cache: false, retry: false, headers: { Authorization: `Bearer ${accessToken}` } });
+        const snapshot = contracts_1.subjectProductGrantSnapshotSchema.parse(answer);
+        if (snapshot.access.subjectAccountId !== parsed.subjectAccountId || snapshot.access.productId !== parsed.productId)
+            throw new Error('Product grant response attribution differs');
+        return snapshot;
+    }
+    /** Offline metering read: the API requires this app's live consent for this exact subject. */
+    async productGrantSnapshotForService(query) {
+        const parsed = contracts_1.subjectProductAccessQuerySchema.parse(query);
+        const answer = await this.serviceRequest('GET', `/v1/products/${encodeURIComponent(parsed.productId)}/access/${encodeURIComponent(parsed.subjectAccountId)}/service-grants`, undefined, { cache: false, retry: false });
+        const snapshot = contracts_1.subjectProductGrantSnapshotSchema.parse(answer);
+        if (snapshot.access.subjectAccountId !== parsed.subjectAccountId || snapshot.access.productId !== parsed.productId)
+            throw new Error('Product grant response attribution differs');
+        return snapshot;
+    }
     async serviceRequest(method, url, data, options = {}) {
         const { actAs, headers, ...rest } = options;
         const token = await this.serviceToken();

package/dist/esm/api/assets.js

@@ -34,6 +34,12 @@ const ASSET_URL_CACHE_LIFETIME_FRACTION = 0.5;
 /** Assumed URL lifetime (seconds) when no `expiresIn` is asked for; the API default. */
 const DEFAULT_ASSET_URL_EXPIRES_IN_SECONDS = 3600;
 const ASSET_TTL = 5 * 60 * 1000;
+/**
+ * Default bound on one `POST /assets/upload`, in ms. The client's per-request
+ * default (5s) is sized for JSON calls; a video sent over a phone connection
+ * needs minutes, and timing it out at 5s failed every upload past a few MB.
+ */
+const ASSET_UPLOAD_TIMEOUT_MS = 10 * 60 * 1000;
 /**
  * How long a resolved asset URL may stay in the SDK's GET cache, in ms: never
  * longer than the media token's lifetime, and discounted below it.
@@ -47,6 +53,24 @@ export class AssetsApi {
     constructor(ctx) {
         this.ctx = ctx;
     }
+    /** Upload already-admitted bytes. Sends required bucket headers, never an Oxy bearer. */
+    async putPresignedUpload(init, body) {
+        if (!init.uploadUrl)
+            return; // bytes already exist for this account
+        const target = new URL(init.uploadUrl);
+        if (target.protocol !== 'https:')
+            throw new Error('Presigned uploads require HTTPS');
+        const headers = new Headers(init.requiredHeaders);
+        headers.forEach((_value, name) => {
+            if (!['if-none-match', 'content-type', 'x-amz-checksum-sha256', 'cache-control'].includes(name.toLowerCase()))
+                throw new Error('Unsupported required upload header');
+        });
+        if (body.type && !headers.has('Content-Type'))
+            headers.set('Content-Type', body.type);
+        const result = await fetch(target.toString(), { method: 'PUT', body, headers, credentials: 'omit', redirect: 'error' });
+        if (!result.ok)
+            throw new Error(`Presigned upload failed (${result.status})`);
+    }
     // ── Upload ───────────────────────────────────────────────────────────────
     /**
      * Upload a file. Accepts a web `File`/`Blob` or a React Native
@@ -92,7 +116,10 @@ export class AssetsApi {
         if (options.metadata)
             formData.append('metadata', JSON.stringify(options.metadata));
         try {
-            const response = await this.ctx.request('POST', '/assets/upload', formData, { cache: false });
+            const response = await this.ctx.request('POST', '/assets/upload', formData, {
+                cache: false,
+                timeout: options.timeout ?? ASSET_UPLOAD_TIMEOUT_MS,
+            });
             options.onProgress?.(100);
             return response;
         }

package/dist/esm/api/auth.js

@@ -672,14 +672,19 @@ export class AuthApi {
         this.agent = new AuthAgentApi(ctx);
     }
     /**
-     * Register a new identity with public key authentication
-     * Identity is purely cryptographic - username and profile data are optional
+     * Register a new account for a public key, together with its username.
+     *
+     * The username is required: the server writes it in the same insert as the
+     * key, so an account never exists without one. A taken username is a 409
+     * (`Username already taken`), as is a key that is already registered
+     * (`Identity already registered`).
      *
      * @param publicKey - The user's ECDSA public key (hex)
      * @param signature - Signature of the registration request
      * @param timestamp - Timestamp when the signature was created
+     * @param username - The account's username
      */
-    async registerKey(publicKey, signature, timestamp) {
+    async registerKey(publicKey, signature, timestamp, username) {
         // Advisory for now (server soft-enforces — see
         // `SessionController.register`), but solved unconditionally so every
         // client is already sending it once the server starts requiring it.
@@ -689,6 +694,7 @@ export class AuthApi {
             publicKey,
             signature,
             timestamp,
+            username,
             powNonce,
         }, { cache: false, skipAuth: true });
         if (!res || (typeof res === 'object' && Object.keys(res).length === 0)) {

package/dist/esm/api/billing.js

@@ -1,3 +1,4 @@
+import { personalPlanCheckoutRequestSchema, personalPlanCheckoutResultSchema } from '@oxy.so/contracts';
 /**
  * `oxy.billing` — the signed-in user's subscription, wallet and payment history.
  *
@@ -9,6 +10,7 @@
  * `payment.controller`, `wallet.routes` in `packages/api`); `Date` columns
  * arrive as ISO-8601 strings.
  */
+import { personalPlanCatalogueSchema } from '@oxy.so/contracts';
 import { subjectProductAccessQuerySchema, subjectProductAccessSchema, } from '@oxy.so/contracts';
 import { productSubscriptionCancellationResultSchema, cancelProductSubscriptionSchema, productSubscriptionsResponseSchema, subscriptionCreditGrantsResponseSchema, } from '@oxy.so/contracts';
 const SUBSCRIPTION_TTL = 2 * 60 * 1000;
@@ -17,6 +19,13 @@ export class BillingApi {
     constructor(ctx) {
         this.ctx = ctx;
     }
+    async startPersonalPlanCheckout(request) {
+        return personalPlanCheckoutResultSchema.parse(await this.ctx.request('POST', '/billing/checkout/personal-plan', personalPlanCheckoutRequestSchema.parse(request), { cache: false }));
+    }
+    /** Public versioned personal plans. Discovery never proves customer access. */
+    async personalPlans() {
+        return personalPlanCatalogueSchema.parse(await this.ctx.request('GET', '/billing/personal-plans', undefined, { cache: false }));
+    }
     /** Product rights only; requires a production application-bound user session. Never cached. */
     async productAccess(query) {
         const parsed = subjectProductAccessQuerySchema.parse(query);
@@ -24,20 +33,20 @@ export class BillingApi {
         return subjectProductAccessSchema.parse(response);
     }
     /** Named commercial sources for the current subject; no inferred plan collapse. */
-    async productSubscriptions() {
-        return productSubscriptionsResponseSchema.parse(await this.ctx.request("GET", "/billing/product-subscriptions", undefined, { cache: false })).subscriptions;
+    async productSubscriptions(expectedSubjectAccountId) {
+        return productSubscriptionsResponseSchema.parse(await this.ctx.request("GET", expectedSubjectAccountId ? `/billing/product-subscriptions?expectedSubjectAccountId=${encodeURIComponent(expectedSubjectAccountId)}` : "/billing/product-subscriptions", undefined, { cache: false })).subscriptions;
     }
     /** Per-grant credit provenance; no interpretation of the historical mixed balance. */
     async creditGrants() {
         return subscriptionCreditGrantsResponseSchema.parse(await this.ctx.request("GET", "/billing/credit-grants", undefined, { cache: false })).grants;
     }
     /** Payer-only named-source cancellation. Resolves on provider acceptance, including pending local reconciliation. Use cancelProductSubscriptionWithStatus for detailed completion state. */
-    async cancelProductSubscription(sourceId, expectedSubjectAccountId) {
-        await this.ctx.request("POST", "/billing/product-subscriptions/cancel", cancelProductSubscriptionSchema.parse({ sourceId, ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }), { cache: false });
+    async cancelProductSubscription(sourceId, expectedSubjectAccountId, actionId) {
+        await this.ctx.request("POST", "/billing/product-subscriptions/cancel", cancelProductSubscriptionSchema.parse({ sourceId, ...(actionId ? { actionId } : {}), ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }), { cache: false });
     }
     /** Provider acceptance versus completed local cancellation, for user-facing flows. */
-    async cancelProductSubscriptionWithStatus(sourceId, expectedSubjectAccountId) {
-        return productSubscriptionCancellationResultSchema.parse(await this.ctx.request('POST', '/billing/product-subscriptions/cancel', cancelProductSubscriptionSchema.parse({ sourceId, ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }), { cache: false }));
+    async cancelProductSubscriptionWithStatus(sourceId, expectedSubjectAccountId, actionId) {
+        return productSubscriptionCancellationResultSchema.parse(await this.ctx.request('POST', '/billing/product-subscriptions/cancel', cancelProductSubscriptionSchema.parse({ sourceId, ...(actionId ? { actionId } : {}), ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }), { cache: false }));
     }
     /** The signed-in user's payment history. Never cached. */
     async payments() {

package/dist/esm/api/users.js

@@ -73,8 +73,8 @@ export class UsersApi {
         return settled.flat();
     }
     /** The signed-in user. Cached 1 minute. */
-    async me() {
-        const user = await this.ctx.request('GET', '/users/me', undefined, { cache: true, cacheTTL: ME_TTL });
+    async me(options) {
+        const user = await this.ctx.request('GET', '/users/me', undefined, { cache: options?.cache ?? true, cacheTTL: ME_TTL });
         return normalizeUserIdentity(user);
     }
     /** A profile by username. Cached 5 minutes; `{ cache: false }` as in `get`. */

package/dist/esm/server/OxyServer.js

@@ -1,3 +1,4 @@
+import { subjectProductAccessQuerySchema, subjectProductGrantSnapshotSchema } from '@oxy.so/contracts';
 /**
  * `OxyServer` — the Oxy client for a backend.
  *
@@ -275,6 +276,26 @@ export class OxyServer extends OxyServices {
      * request is on behalf of that user (the API checks the delegation grant).
      * Never cached unless `cache` says so. Rejects with `OxyApiError`.
      */
+    /** Validated request's user session only; never changes the shared client's token. */
+    async productGrantSnapshotForUser(query, accessToken) {
+        const parsed = subjectProductAccessQuerySchema.parse(query);
+        if (!accessToken || /[\r\n]/.test(accessToken))
+            throw new Error('A user session is required');
+        const answer = await this.request('GET', `/v1/products/${encodeURIComponent(parsed.productId)}/access/${encodeURIComponent(parsed.subjectAccountId)}/grants`, undefined, { cache: false, retry: false, headers: { Authorization: `Bearer ${accessToken}` } });
+        const snapshot = subjectProductGrantSnapshotSchema.parse(answer);
+        if (snapshot.access.subjectAccountId !== parsed.subjectAccountId || snapshot.access.productId !== parsed.productId)
+            throw new Error('Product grant response attribution differs');
+        return snapshot;
+    }
+    /** Offline metering read: the API requires this app's live consent for this exact subject. */
+    async productGrantSnapshotForService(query) {
+        const parsed = subjectProductAccessQuerySchema.parse(query);
+        const answer = await this.serviceRequest('GET', `/v1/products/${encodeURIComponent(parsed.productId)}/access/${encodeURIComponent(parsed.subjectAccountId)}/service-grants`, undefined, { cache: false, retry: false });
+        const snapshot = subjectProductGrantSnapshotSchema.parse(answer);
+        if (snapshot.access.subjectAccountId !== parsed.subjectAccountId || snapshot.access.productId !== parsed.productId)
+            throw new Error('Product grant response attribution differs');
+        return snapshot;
+    }
     async serviceRequest(method, url, data, options = {}) {
         const { actAs, headers, ...rest } = options;
         const token = await this.serviceToken();

package/dist/types/api/assets.d.ts

@@ -1,5 +1,5 @@
 import type { OxyContext } from '../client/context';
-import type { AccountStorageUsageResponse, Asset, AssetDeleteSummary, AssetLink, AssetMetadata, AssetUploadInput, BatchFileAccessResponse, FileVisibility } from '../models/interfaces';
+import type { AccountStorageUsageResponse, AssetInitResponse, Asset, AssetDeleteSummary, AssetLink, AssetMetadata, AssetUploadInput, BatchFileAccessResponse, FileVisibility } from '../models/interfaces';
 /**
  * How long a resolved asset URL may stay in the SDK's GET cache, in ms: never
  * longer than the media token's lifetime, and discounted below it.
@@ -27,6 +27,8 @@ export interface AssetUploadOptions {
     metadata?: AssetMetadata;
     /** Called with `100` once the upload completes. */
     onProgress?: (progress: number) => void;
+    /** Bound on the whole upload, in ms. Default {@link ASSET_UPLOAD_TIMEOUT_MS}. */
+    timeout?: number;
 }
 export interface AssetLinkTarget {
     app: string;
@@ -41,6 +43,8 @@ export interface AssetDeleteResult {
 export declare class AssetsApi {
     protected readonly ctx: OxyContext;
     constructor(ctx: OxyContext);
+    /** Upload already-admitted bytes. Sends required bucket headers, never an Oxy bearer. */
+    putPresignedUpload(init: AssetInitResponse, body: Blob): Promise<void>;
     /**
      * Upload a file. Accepts a web `File`/`Blob` or a React Native
      * `{ uri, type?, name?, size? }` descriptor.

package/dist/types/api/auth.d.ts

@@ -633,14 +633,19 @@ export declare class AuthApi {
     readonly agent: AuthAgentApi;
     constructor(ctx: OxyContext);
     /**
-     * Register a new identity with public key authentication
-     * Identity is purely cryptographic - username and profile data are optional
+     * Register a new account for a public key, together with its username.
+     *
+     * The username is required: the server writes it in the same insert as the
+     * key, so an account never exists without one. A taken username is a 409
+     * (`Username already taken`), as is a key that is already registered
+     * (`Identity already registered`).
      *
      * @param publicKey - The user's ECDSA public key (hex)
      * @param signature - Signature of the registration request
      * @param timestamp - Timestamp when the signature was created
+     * @param username - The account's username
      */
-    registerKey(publicKey: string, signature: string, timestamp: number): Promise<{
+    registerKey(publicKey: string, signature: string, timestamp: number, username: string): Promise<{
         message: string;
         user: User;
     }>;

package/dist/types/api/billing.d.ts

@@ -1,3 +1,4 @@
+import { type PersonalPlanCheckoutRequest, type PersonalPlanCheckoutResult } from '@oxy.so/contracts';
 /**
  * `oxy.billing` — the signed-in user's subscription, wallet and payment history.
  *
@@ -9,6 +10,7 @@
  * `payment.controller`, `wallet.routes` in `packages/api`); `Date` columns
  * arrive as ISO-8601 strings.
  */
+import { type PersonalPlanCatalogue } from '@oxy.so/contracts';
 import { type SubjectProductAccess, type SubjectProductAccessQuery } from '@oxy.so/contracts';
 import { type ProductSubscriptionSummary, type SubscriptionCreditGrant, type ProductSubscriptionCancellationResult } from '@oxy.so/contracts';
 import type { OxyContext } from '../client/context';
@@ -99,16 +101,19 @@ export interface WalletTransactionsPage {
 export declare class BillingApi {
     protected readonly ctx: OxyContext;
     constructor(ctx: OxyContext);
+    startPersonalPlanCheckout(request: PersonalPlanCheckoutRequest): Promise<PersonalPlanCheckoutResult>;
+    /** Public versioned personal plans. Discovery never proves customer access. */
+    personalPlans(): Promise<PersonalPlanCatalogue>;
     /** Product rights only; requires a production application-bound user session. Never cached. */
     productAccess(query: SubjectProductAccessQuery): Promise<SubjectProductAccess>;
     /** Named commercial sources for the current subject; no inferred plan collapse. */
-    productSubscriptions(): Promise<ProductSubscriptionSummary[]>;
+    productSubscriptions(expectedSubjectAccountId?: string): Promise<ProductSubscriptionSummary[]>;
     /** Per-grant credit provenance; no interpretation of the historical mixed balance. */
     creditGrants(): Promise<SubscriptionCreditGrant[]>;
     /** Payer-only named-source cancellation. Resolves on provider acceptance, including pending local reconciliation. Use cancelProductSubscriptionWithStatus for detailed completion state. */
-    cancelProductSubscription(sourceId: string, expectedSubjectAccountId?: string): Promise<void>;
+    cancelProductSubscription(sourceId: string, expectedSubjectAccountId?: string, actionId?: string): Promise<void>;
     /** Provider acceptance versus completed local cancellation, for user-facing flows. */
-    cancelProductSubscriptionWithStatus(sourceId: string, expectedSubjectAccountId?: string): Promise<ProductSubscriptionCancellationResult>;
+    cancelProductSubscriptionWithStatus(sourceId: string, expectedSubjectAccountId?: string, actionId?: string): Promise<ProductSubscriptionCancellationResult>;
     /** The signed-in user's payment history. Never cached. */
     payments(): Promise<Payment[]>;
     /** A user's subscription (default: the signed-in user's). */

package/dist/types/api/users.d.ts

@@ -61,7 +61,9 @@ export declare class UsersApi {
      */
     getMany(ids: string[]): Promise<User[]>;
     /** The signed-in user. Cached 1 minute. */
-    me(): Promise<User>;
+    me(options?: {
+        cache?: boolean;
+    }): Promise<User>;
     /** A profile by username. Cached 5 minutes; `{ cache: false }` as in `get`. */
     byUsername(username: string, options?: {
         cache?: boolean;

package/dist/types/models/interfaces.d.ts

@@ -200,6 +200,13 @@ export interface User {
      * user sets it. Updated via `updateThemePreference` / `updateProfile`.
      */
     themePreference?: ThemePreference;
+    /** Product-specific personalization; never inferred from generic premium. */
+    personalization?: {
+        mentionMono: {
+            allowed: boolean;
+            expiresAt: string | null;
+        };
+    };
     /**
      * The authenticated viewer's relationship to THIS profile. Populated ONLY on
      * single-profile fetches (`getProfileByUsername` / `getUserById`) when the
@@ -520,6 +527,8 @@ export interface AssetInitRequest {
     mime: string;
 }
 export interface AssetInitResponse {
+    /** Replay these headers on PUT; Content-Length is supplied by the transport. */
+    requiredHeaders?: Record<string, string>;
     uploadUrl: string;
     fileId: string;
     sha256: string;
@@ -694,6 +703,8 @@ export interface AccountStorageCategoryUsage {
     count: number;
 }
 export interface AccountStorageUsageResponse {
+    quotaEnforcement?: 'metadata_admission' | 'unconfigured';
+    reservedBytes?: string | null;
     plan: 'basic' | 'pro' | 'business';
     totalUsedBytes: number;
     totalLimitBytes: number;

package/dist/types/server/OxyServer.d.ts

@@ -1,3 +1,4 @@
+import { type SubjectProductAccessQuery, type SubjectProductGrantSnapshot } from '@oxy.so/contracts';
 import { OxyServices, type OxyConfig } from '../OxyServices';
 import type { HttpMethod } from '../client/context';
 import type { RequestOptions } from '../HttpService';
@@ -132,6 +133,10 @@ export declare class OxyServer extends OxyServices {
      * request is on behalf of that user (the API checks the delegation grant).
      * Never cached unless `cache` says so. Rejects with `OxyApiError`.
      */
+    /** Validated request's user session only; never changes the shared client's token. */
+    productGrantSnapshotForUser(query: SubjectProductAccessQuery, accessToken: string): Promise<SubjectProductGrantSnapshot>;
+    /** Offline metering read: the API requires this app's live consent for this exact subject. */
+    productGrantSnapshotForService(query: SubjectProductAccessQuery): Promise<SubjectProductGrantSnapshot>;
     serviceRequest<T>(method: HttpMethod, url: string, data?: unknown, options?: RequestOptions & {
         actAs?: string;
     }): Promise<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "4.4.0",
+  "version": "4.5.0-oxy-one.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -179,7 +179,7 @@
     "@oxy.so/telemetry": "^1.2.0",
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxy.so/contracts": "^4.9.1",
+    "@oxy.so/contracts": "4.11.0-oxy-one.0",
     "@oxy.so/protocol": "^1.2.2",
     "@scure/bip39": "^1.6.0",
     "buffer": "^6.0.3",

package/src/api/assets.ts

@@ -18,6 +18,7 @@ import type { OxyContext } from '../client/context';
 import { logger } from '../logger';
 import type {
   AccountStorageUsageResponse,
+  AssetInitResponse,
   Asset,
   AssetDeleteSummary,
   AssetLink,
@@ -51,6 +52,13 @@ const DEFAULT_ASSET_URL_EXPIRES_IN_SECONDS = 3600;
 
 const ASSET_TTL = 5 * 60 * 1000;
 
+/**
+ * Default bound on one `POST /assets/upload`, in ms. The client's per-request
+ * default (5s) is sized for JSON calls; a video sent over a phone connection
+ * needs minutes, and timing it out at 5s failed every upload past a few MB.
+ */
+const ASSET_UPLOAD_TIMEOUT_MS = 10 * 60 * 1000;
+
 /**
  * How long a resolved asset URL may stay in the SDK's GET cache, in ms: never
  * longer than the media token's lifetime, and discounted below it.
@@ -84,6 +92,8 @@ export interface AssetUploadOptions {
   metadata?: AssetMetadata;
   /** Called with `100` once the upload completes. */
   onProgress?: (progress: number) => void;
+  /** Bound on the whole upload, in ms. Default {@link ASSET_UPLOAD_TIMEOUT_MS}. */
+  timeout?: number;
 }
 
 export interface AssetLinkTarget {
@@ -101,6 +111,21 @@ export interface AssetDeleteResult {
 export class AssetsApi {
   constructor(protected readonly ctx: OxyContext) {}
 
+  /** Upload already-admitted bytes. Sends required bucket headers, never an Oxy bearer. */
+  async putPresignedUpload(init: AssetInitResponse, body: Blob): Promise<void> {
+    if (!init.uploadUrl) return; // bytes already exist for this account
+    const target = new URL(init.uploadUrl);
+    if (target.protocol !== 'https:') throw new Error('Presigned uploads require HTTPS');
+    const headers = new Headers(init.requiredHeaders);
+    headers.forEach((_value,name) => {
+      if (!['if-none-match','content-type','x-amz-checksum-sha256','cache-control'].includes(name.toLowerCase()))
+        throw new Error('Unsupported required upload header');
+    });
+    if (body.type && !headers.has('Content-Type')) headers.set('Content-Type',body.type);
+    const result = await fetch(target.toString(),{method:'PUT',body,headers,credentials:'omit',redirect:'error'});
+    if(!result.ok)throw new Error(`Presigned upload failed (${result.status})`);
+  }
+
   // ── Upload ───────────────────────────────────────────────────────────────
 
   /**
@@ -144,7 +169,10 @@ export class AssetsApi {
     if (options.metadata) formData.append('metadata', JSON.stringify(options.metadata));
 
     try {
-      const response = await this.ctx.request<{ file: UploadedAsset }>('POST', '/assets/upload', formData, { cache: false });
+      const response = await this.ctx.request<{ file: UploadedAsset }>('POST', '/assets/upload', formData, {
+        cache: false,
+        timeout: options.timeout ?? ASSET_UPLOAD_TIMEOUT_MS,
+      });
       options.onProgress?.(100);
       return response;
     } catch (error) {

package/src/api/auth.ts

@@ -1208,17 +1208,23 @@ export class AuthApi {
   }
 
   /**
-   * Register a new identity with public key authentication
-   * Identity is purely cryptographic - username and profile data are optional
-   * 
+   * Register a new account for a public key, together with its username.
+   *
+   * The username is required: the server writes it in the same insert as the
+   * key, so an account never exists without one. A taken username is a 409
+   * (`Username already taken`), as is a key that is already registered
+   * (`Identity already registered`).
+   *
    * @param publicKey - The user's ECDSA public key (hex)
    * @param signature - Signature of the registration request
    * @param timestamp - Timestamp when the signature was created
+   * @param username - The account's username
    */
   async registerKey(
     publicKey: string,
     signature: string,
-    timestamp: number
+    timestamp: number,
+    username: string
   ): Promise<{ message: string; user: User }> {
     // Advisory for now (server soft-enforces — see
     // `SessionController.register`), but solved unconditionally so every
@@ -1230,6 +1236,7 @@ export class AuthApi {
       publicKey,
       signature,
       timestamp,
+      username,
       powNonce,
     }, { cache: false, skipAuth: true });
 

package/src/api/billing.ts

@@ -1,3 +1,4 @@
+import { personalPlanCheckoutRequestSchema, personalPlanCheckoutResultSchema, type PersonalPlanCheckoutRequest, type PersonalPlanCheckoutResult } from '@oxy.so/contracts';
 /**
  * `oxy.billing` — the signed-in user's subscription, wallet and payment history.
  *
@@ -9,6 +10,7 @@
  * `payment.controller`, `wallet.routes` in `packages/api`); `Date` columns
  * arrive as ISO-8601 strings.
  */
+import { personalPlanCatalogueSchema, type PersonalPlanCatalogue } from '@oxy.so/contracts';
 import { type SubjectProductAccess,
 	type SubjectProductAccessQuery,
 	subjectProductAccessQuerySchema, subjectProductAccessSchema, } from '@oxy.so/contracts';
@@ -115,6 +117,17 @@ export interface WalletTransactionsPage {
 export class BillingApi {
   constructor(protected readonly ctx: OxyContext) {}
 
+  async startPersonalPlanCheckout(request: PersonalPlanCheckoutRequest): Promise<PersonalPlanCheckoutResult> {
+    return personalPlanCheckoutResultSchema.parse(await this.ctx.request<unknown>('POST', '/billing/checkout/personal-plan',
+      personalPlanCheckoutRequestSchema.parse(request), { cache: false }));
+  }
+
+  /** Public versioned personal plans. Discovery never proves customer access. */
+  async personalPlans(): Promise<PersonalPlanCatalogue> {
+    return personalPlanCatalogueSchema.parse(await this.ctx.request<unknown>(
+      'GET', '/billing/personal-plans', undefined, { cache: false }));
+  }
+
   /** Product rights only; requires a production application-bound user session. Never cached. */
   async productAccess(query: SubjectProductAccessQuery): Promise<SubjectProductAccess> {
     const parsed = subjectProductAccessQuerySchema.parse(query);
@@ -125,11 +138,11 @@ export class BillingApi {
   }
 
 	/** Named commercial sources for the current subject; no inferred plan collapse. */
-	async productSubscriptions(): Promise<ProductSubscriptionSummary[]> {
+	async productSubscriptions(expectedSubjectAccountId?: string): Promise<ProductSubscriptionSummary[]> {
 		return productSubscriptionsResponseSchema.parse(
 			await this.ctx.request<unknown>(
 				"GET",
-				"/billing/product-subscriptions",
+				expectedSubjectAccountId ? `/billing/product-subscriptions?expectedSubjectAccountId=${encodeURIComponent(expectedSubjectAccountId)}` : "/billing/product-subscriptions",
 				undefined,
 				{ cache: false },
 			),
@@ -149,20 +162,20 @@ export class BillingApi {
 	}
 
 	/** Payer-only named-source cancellation. Resolves on provider acceptance, including pending local reconciliation. Use cancelProductSubscriptionWithStatus for detailed completion state. */
-	async cancelProductSubscription(sourceId: string, expectedSubjectAccountId?: string): Promise<void> {
+	async cancelProductSubscription(sourceId: string, expectedSubjectAccountId?: string, actionId?:string): Promise<void> {
 		await this.ctx.request(
 			"POST",
 			"/billing/product-subscriptions/cancel",
-			cancelProductSubscriptionSchema.parse({ sourceId, ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }),
+			cancelProductSubscriptionSchema.parse({ sourceId, ...(actionId?{actionId}:{}), ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }),
 			{ cache: false },
 		);
 	}
 
   /** Provider acceptance versus completed local cancellation, for user-facing flows. */
-  async cancelProductSubscriptionWithStatus(sourceId: string, expectedSubjectAccountId?: string): Promise<ProductSubscriptionCancellationResult> {
+  async cancelProductSubscriptionWithStatus(sourceId: string, expectedSubjectAccountId?: string, actionId?:string): Promise<ProductSubscriptionCancellationResult> {
     return productSubscriptionCancellationResultSchema.parse(await this.ctx.request<unknown>(
       'POST', '/billing/product-subscriptions/cancel',
-      cancelProductSubscriptionSchema.parse({ sourceId, ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }),
+      cancelProductSubscriptionSchema.parse({ sourceId, ...(actionId?{actionId}:{}), ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }),
       { cache: false },
     ));
   }

package/src/api/users.ts

@@ -121,8 +121,8 @@ export class UsersApi {
   }
 
   /** The signed-in user. Cached 1 minute. */
-  async me(): Promise<User> {
-    const user = await this.ctx.request<User>('GET', '/users/me', undefined, { cache: true, cacheTTL: ME_TTL });
+  async me(options?: {cache?: boolean}): Promise<User> {
+    const user = await this.ctx.request<User>('GET', '/users/me', undefined, { cache: options?.cache ?? true, cacheTTL: ME_TTL });
     return normalizeUserIdentity(user);
   }
 

package/src/models/interfaces.ts

@@ -224,6 +224,8 @@ export interface User {
    * user sets it. Updated via `updateThemePreference` / `updateProfile`.
    */
   themePreference?: ThemePreference;
+  /** Product-specific personalization; never inferred from generic premium. */
+  personalization?: {mentionMono:{allowed:boolean;expiresAt:string|null}};
   /**
    * The authenticated viewer's relationship to THIS profile. Populated ONLY on
    * single-profile fetches (`getProfileByUsername` / `getUserById`) when the
@@ -581,6 +583,8 @@ export interface AssetInitRequest {
 }
 
 export interface AssetInitResponse {
+  /** Replay these headers on PUT; Content-Length is supplied by the transport. */
+  requiredHeaders?: Record<string, string>;
   uploadUrl: string;
   fileId: string;
   sha256: string;
@@ -769,6 +773,8 @@ export interface AccountStorageCategoryUsage {
 }
 
 export interface AccountStorageUsageResponse {
+  quotaEnforcement?: 'metadata_admission' | 'unconfigured';
+  reservedBytes?: string | null;
   plan: 'basic' | 'pro' | 'business';
   totalUsedBytes: number;
   totalLimitBytes: number;

package/src/server/OxyServer.ts

@@ -1,3 +1,4 @@
+import { subjectProductAccessQuerySchema, subjectProductGrantSnapshotSchema, type SubjectProductAccessQuery, type SubjectProductGrantSnapshot } from '@oxy.so/contracts';
 /**
  * `OxyServer` — the Oxy client for a backend.
  *
@@ -362,6 +363,31 @@ export class OxyServer extends OxyServices {
    * request is on behalf of that user (the API checks the delegation grant).
    * Never cached unless `cache` says so. Rejects with `OxyApiError`.
    */
+  /** Validated request's user session only; never changes the shared client's token. */
+  async productGrantSnapshotForUser(query: SubjectProductAccessQuery, accessToken: string): Promise<SubjectProductGrantSnapshot> {
+    const parsed = subjectProductAccessQuerySchema.parse(query);
+    if (!accessToken || /[\r\n]/.test(accessToken)) throw new Error('A user session is required');
+    const answer = await this.request<unknown>('GET',
+      `/v1/products/${encodeURIComponent(parsed.productId)}/access/${encodeURIComponent(parsed.subjectAccountId)}/grants`,
+      undefined, { cache: false, retry: false, headers: { Authorization: `Bearer ${accessToken}` } });
+    const snapshot = subjectProductGrantSnapshotSchema.parse(answer);
+    if(snapshot.access.subjectAccountId !== parsed.subjectAccountId || snapshot.access.productId !== parsed.productId)
+      throw new Error('Product grant response attribution differs');
+    return snapshot;
+  }
+
+  /** Offline metering read: the API requires this app's live consent for this exact subject. */
+  async productGrantSnapshotForService(query: SubjectProductAccessQuery): Promise<SubjectProductGrantSnapshot> {
+    const parsed = subjectProductAccessQuerySchema.parse(query);
+    const answer = await this.serviceRequest<unknown>('GET',
+      `/v1/products/${encodeURIComponent(parsed.productId)}/access/${encodeURIComponent(parsed.subjectAccountId)}/service-grants`,
+      undefined, { cache: false, retry: false });
+    const snapshot = subjectProductGrantSnapshotSchema.parse(answer);
+    if (snapshot.access.subjectAccountId !== parsed.subjectAccountId || snapshot.access.productId !== parsed.productId)
+      throw new Error('Product grant response attribution differs');
+    return snapshot;
+  }
+
   async serviceRequest<T>(
     method: HttpMethod,
     url: string,