@oxy.so/core 4.0.0 → 4.2.0

package/src/api/billing.ts

@@ -9,6 +9,16 @@
  * `payment.controller`, `wallet.routes` in `packages/api`); `Date` columns
  * arrive as ISO-8601 strings.
  */
+import { type SubjectProductAccess,
+	type SubjectProductAccessQuery,
+	subjectProductAccessQuerySchema, subjectProductAccessSchema, } from '@oxy.so/contracts';
+import {
+	type ProductSubscriptionSummary, type SubscriptionCreditGrant, type ProductSubscriptionCancellationResult,
+  productSubscriptionCancellationResultSchema,
+	cancelProductSubscriptionSchema,
+	productSubscriptionsResponseSchema,
+	subscriptionCreditGrantsResponseSchema,
+} from '@oxy.so/contracts';
 import type { OxyContext } from '../client/context';
 
 const SUBSCRIPTION_TTL = 2 * 60 * 1000;
@@ -105,13 +115,65 @@ export interface WalletTransactionsPage {
 export class BillingApi {
   constructor(protected readonly ctx: OxyContext) {}
 
-  /** The signed-in user's payment history. Never cached. */
-  async payments(): Promise<Payment[]> {
+  /** Product rights only; requires a production application-bound user session. Never cached. */
+  async productAccess(query: SubjectProductAccessQuery): Promise<SubjectProductAccess> {
+    const parsed = subjectProductAccessQuerySchema.parse(query);
+    const response = await this.ctx.request<unknown>('GET',
+      `/v1/products/${encodeURIComponent(parsed.productId)}/access/${encodeURIComponent(parsed.subjectAccountId)}`,
+      undefined, { cache: false });
+    return subjectProductAccessSchema.parse(response);
+  }
+
+	/** Named commercial sources for the current subject; no inferred plan collapse. */
+	async productSubscriptions(): Promise<ProductSubscriptionSummary[]> {
+		return productSubscriptionsResponseSchema.parse(
+			await this.ctx.request<unknown>(
+				"GET",
+				"/billing/product-subscriptions",
+				undefined,
+				{ cache: false },
+			),
+		).subscriptions;
+	}
+
+	/** Per-grant credit provenance; no interpretation of the historical mixed balance. */
+	async creditGrants(): Promise<SubscriptionCreditGrant[]> {
+		return subscriptionCreditGrantsResponseSchema.parse(
+			await this.ctx.request<unknown>(
+				"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: string, expectedSubjectAccountId?: string): Promise<void> {
+		await this.ctx.request(
+			"POST",
+			"/billing/product-subscriptions/cancel",
+			cancelProductSubscriptionSchema.parse({ sourceId, ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }),
+			{ cache: false },
+		);
+	}
+
+  /** Provider acceptance versus completed local cancellation, for user-facing flows. */
+  async cancelProductSubscriptionWithStatus(sourceId: string, expectedSubjectAccountId?: string): Promise<ProductSubscriptionCancellationResult> {
+    return productSubscriptionCancellationResultSchema.parse(await this.ctx.request<unknown>(
+      'POST', '/billing/product-subscriptions/cancel',
+      cancelProductSubscriptionSchema.parse({ sourceId, ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }),
+      { cache: false },
+    ));
+  }
+
+	/** The signed-in user's payment history. Never cached. */
+	async payments(): Promise<Payment[]> {
     return this.ctx.request<Payment[]>('GET', '/payments/user', undefined, { cache: false });
   }
 
-  /** A user's subscription (default: the signed-in user's). */
-  async subscription(userId?: string): Promise<Subscription> {
+	/** A user's subscription (default: the signed-in user's). */
+	async subscription(userId?: string): Promise<Subscription> {
     const id = this.resolveUserId(userId);
     return this.ctx.request<Subscription>('GET', `/subscription/${id}`, undefined, {
       cache: true,
@@ -119,14 +181,14 @@ export class BillingApi {
     });
   }
 
-  /** A user's wallet (default: the signed-in user's). Cached briefly: the balance moves. */
-  async wallet(userId?: string): Promise<Wallet> {
+	/** A user's wallet (default: the signed-in user's). Cached briefly: the balance moves. */
+	async wallet(userId?: string): Promise<Wallet> {
     const id = this.resolveUserId(userId);
     return this.ctx.request<Wallet>('GET', `/wallet/${id}`, undefined, { cache: true, cacheTTL: WALLET_TTL });
   }
 
-  /** A page of a user's wallet transactions (default: the signed-in user's). Never cached. */
-  async walletTransactions(
+	/** A page of a user's wallet transactions (default: the signed-in user's). Never cached. */
+	async walletTransactions(
     options: { userId?: string; limit?: number; offset?: number } = {},
   ): Promise<WalletTransactionsPage> {
     const id = this.resolveUserId(options.userId);
@@ -136,7 +198,7 @@ export class BillingApi {
     return this.ctx.request<WalletTransactionsPage>('GET', `/wallet/transactions/${id}`, params, { cache: false });
   }
 
-  private resolveUserId(userId?: string): string {
+	private resolveUserId(userId?: string): string {
     const id = userId || this.ctx.oxy.session.userId;
     if (!id) throw new Error('User not authenticated');
     return id;

package/src/api/session.ts

@@ -6,7 +6,7 @@
  * token belongs to: validating it, listing the sessions beside it, signing out.
  */
 import { jwtDecode } from 'jwt-decode';
-import type { DeviceProof } from '@oxy.so/contracts';
+import type { AccountActorChain, DeviceProof } from '@oxy.so/contracts';
 import type { OxyContext } from '../client/context';
 import type { ClientSession } from '../models/session';
 import type { User } from '../models/interfaces';
@@ -26,6 +26,8 @@ export interface SessionValidation {
   user: User;
   sessionId?: string;
   source?: string;
+  /** Who acted, and as whom, read off the session row (issue #1520). */
+  actor?: AccountActorChain;
 }
 
 interface AccessTokenClaims {

package/src/boot/sessionColdBoot.ts

@@ -44,17 +44,14 @@ import { runColdBoot, type ColdBootOutcome, type ColdBootStep } from '../utils/c
 import { isNative as detectNative } from '../utils/platform';
 import { logger } from '../logger';
 import { computeIdentityTag } from '../utils/cacheKey';
-import { TOKEN_REFRESH_LEAD_MS, refreshDeviceSecretArm } from '../session/refresh';
+import { TOKEN_REFRESH_LEAD_MS, refreshDeviceSecretArm, refreshSharedDeviceArm } from '../session/refresh';
 import {
   establishIdentitySession,
   resolveIdentityPin,
   type IdentityBinding,
 } from '../session/identitySession';
 import type { IdentityPin } from '../session/identityPin';
-import {
-  decideSharedDeviceJoin,
-  type SharedDeviceCredentialStore,
-} from '../session/sharedDeviceCredential';
+import type { SharedDeviceCredentialStore } from '../session/sharedDeviceCredential';
 import type { OxyServices } from '../OxyServices';
 import type { AuthStateStore, PersistedAuthState } from '../session/authStateStore';
 import type { DeviceSessionState } from '@oxy.so/contracts';
@@ -178,6 +175,8 @@ export async function runSessionColdBoot(
   // Boot-local (not module-level) so it cannot leak across boots or break under
   // bundler re-evaluation.
   let signedOutReason: SignedOutReason = 'no_session';
+  let rejectedLocalHolder = false;
+  let accountRecoverySuperseded = false;
 
   // Boot-local memo for the identity pin. Resolved lazily INSIDE a step so the
   // (local, but storage-backed) read is covered by `overallDeadlineMs`, and
@@ -212,6 +211,7 @@ export async function runSessionColdBoot(
   steps.push({
     id: 'warm-token-plant',
     run: async () => {
+      if (identityBinding === null && isNative && await store.isAutomaticIdentitySignInSuppressed?.()) return { kind: 'skip' };
       const persisted = await store.load();
       if (!persisted?.accessToken || !persisted.sessionId || !persisted.userId || !persisted.expiresAt) {
         return { kind: 'skip' };
@@ -287,6 +287,11 @@ export async function runSessionColdBoot(
             },
           };
         case 'invalid-secret': {
+          if (identityBinding === null && store.setAutomaticIdentitySignInSuppressed && await store.isAutomaticIdentitySignInSuppressed?.()) {
+            rejectedLocalHolder = true;
+            signedOutReason = 'no_session';
+            return {kind: 'skip'};
+          }
           // Stale/diverged secret — drop it so the mint lane stops firing. On
           // native the Commons-proof step below can still recover; on web this ends
           // signed out. Setting it undefined drops the key on the store's JSON
@@ -298,6 +303,7 @@ export async function runSessionColdBoot(
           return { kind: 'skip' };
         }
         case 'no-session':
+          rejectedLocalHolder = identityBinding === null;
           // Device known, no live session — authoritative signed-out. Keep the
           // secret (the device may sign in again).
           signedOutReason = 'no_session';
@@ -329,7 +335,9 @@ export async function runSessionColdBoot(
           );
           return { kind: 'skip' };
         case 'session-ended':
-          // Signed out while the boot was minting; the arm planted nothing.
+          // The prior holder/epoch was superseded. This boot must not turn a
+          // late rejection into a fresh Commons sign-in; a new boot can reconcile.
+          if (identityBinding === null) accountRecoverySuperseded = true;
           return { kind: 'skip' };
         case 'no-secret':
           return { kind: 'skip' };
@@ -394,73 +402,16 @@ export async function runSessionColdBoot(
       // The adoption itself is local, but it is only worth committing alongside
       // a mint that proves the credential — so the whole lane is online-gated
       // like every other network step.
-      enabled: () => isNative && !isOffline(),
+      enabled: () => isNative && !isOffline() && !accountRecoverySuperseded,
       run: async () => {
-        const before = await store.load();
-        const decision = decideSharedDeviceJoin(before, await sharedSlot.read());
-        if (decision.action === 'skip') {
-          logger.debug(
-            `shared device credential not adopted (${decision.reason})`,
-            { component: 'sessionColdBoot', method: 'shared-device-adopt' },
-          );
-          return { kind: 'skip' };
-        }
-
-        // Restore the store to exactly what it held before this lane touched it.
-        // A credential we adopted and could not prove must not be left behind for
-        // the next boot's mint lane to keep retrying.
-        const revert = async (): Promise<void> => {
-          if (before) {
-            await store.save(before);
-          } else {
-            await store.clear();
-          }
-        };
-
-        const adopted: PersistedAuthState = {
-          // The mint fills both in from the device's live state; carrying the
-          // previous session's ids into a different device session would be a
-          // lie for however long the mint takes.
-          sessionId: '',
-          userId: '',
-          deviceId: decision.credential.deviceId,
-          deviceSecret: decision.credential.deviceSecret,
-        };
-        if (!(await store.save(adopted))) {
-          logger.error(
-            'adopted the shared device credential but it could not be durably persisted — reverting',
-            undefined,
-            { component: 'sessionColdBoot', method: 'shared-device-adopt' },
-          );
-          await revert();
-          return { kind: 'skip' };
-        }
-
-        const result = await refreshDeviceSecretArm({ oxy, store, pin: null });
+        const result = await refreshSharedDeviceArm({oxy, store, shared: sharedSlot, rejectedLocalHolder});
         if (result.status === 'ok') {
-          return {
-            kind: 'session',
-            session: {
-              sessionId: result.sessionId,
-              userId: result.userId,
-              accessToken: result.token,
-            },
-          };
+          return {kind: 'session', session: {
+            sessionId: result.sessionId, userId: result.userId, accessToken: result.token, state: result.state,
+          }};
         }
-
-        if (result.status === 'invalid-secret') {
-          // The one place we hold POSITIVE proof that the exact bytes in the
-          // shared slot are dead — the server rejected them by name. Clearing it
-          // signs nobody out (a credential the server does not recognise cannot
-          // be minting for anyone) and it is what stops a dead credential from
-          // blocking every future install: a stale slot owned by a different
-          // `deviceId` is otherwise never overwritten, by design.
-          await sharedSlot.clear();
-        } else if (result.status === 'no-session') {
-          signedOutReason = 'no_session';
-        }
-        await revert();
-        return { kind: 'skip' };
+        if (result.status === 'no-session') signedOutReason = 'no_session';
+        return {kind: 'skip'};
       },
     });
   }
@@ -488,8 +439,10 @@ export async function runSessionColdBoot(
       id: 'commons-proof-signin',
       enabled: () => isNative && !isOffline(),
       run: async () => {
-        const session = await oxy.auth.signInWithCommonsIdentity({ requestOptions: { retry: false } });
-        if (!session?.accessToken) {
+        if (accountRecoverySuperseded || await store.isAutomaticIdentitySignInSuppressed?.()) return { kind: 'skip' };
+        const epoch = oxy.http.getSessionEpoch();
+        const session = await oxy.auth.signInWithCommonsIdentity({ plantTokens: false, requestOptions: { retry: false } });
+        if (!session?.accessToken || oxy.http.getSessionEpoch() !== epoch || await store.isAutomaticIdentitySignInSuppressed?.()) {
           return { kind: 'skip' };
         }
         // `verifyChallenge` issues a deviceSecret; persist it so the next
@@ -505,6 +458,8 @@ export async function runSessionColdBoot(
             expiresAt: session.expiresAt,
           });
         }
+        if (oxy.http.getSessionEpoch() !== epoch || await store.isAutomaticIdentitySignInSuppressed?.()) return { kind: 'skip' };
+        oxy.session.setAccessToken(session.accessToken);
         return {
           kind: 'session',
           session: {

package/src/index.ts

@@ -40,7 +40,7 @@ export {
   ServiceAssetMetadataError,
 } from './OxyServices.errors';
 export type { HttpMethod } from './client/context';
-export type { RequestOptions, AuthenticatedResponseRequest, AuthRefreshReason, AuthRefreshHandler } from './HttpService';
+export type { RequestOptions, ResponseRequest, ResponseTransport, AuthenticatedResponseRequest, AuthRefreshReason, AuthRefreshHandler } from './HttpService';
 
 // The namespaces — their classes (for typing) and their input/output types.
 export type { SessionApi, DeviceCredentialProvider, SessionValidation } from './api/session';

package/src/inference/OxyInferenceClient.ts

@@ -1,3 +1,4 @@
+import type { MeteredGeneration } from '@oxy.so/contracts';
 /**
  * The Oxy inference client — one surface, two credential lanes (issue #972,
  * workstream 15).
@@ -50,6 +51,8 @@
  * request.
  */
 
+import { decisionRequestSchema, decisionSuccessSchema, decisionAnswersMatch, type DecisionRequest, type DecisionSuccess } from '@oxy.so/contracts';
+
 import type {
     CurrencyCode,
     ExactDecimal,
@@ -261,6 +264,9 @@ export interface OxyGenerationReceipt {
     readonly settledAt: string;
 }
 
+/** The endpoint returns either a customer receipt or internal technical usage. */
+export type OxyGenerationRecord = OxyGenerationReceipt | MeteredGeneration;
+
 /**
  * Anything the inference API refused.
  *
@@ -471,6 +477,27 @@ export class OxyInferenceClient {
         });
     }
 
+    /** Typed nonstreaming decisions. Idempotency conflicts are never replayed or retried. */
+    async decide(
+        request: DecisionRequest,
+        options: OxyInferenceRequestOptions = {},
+    ): Promise<DecisionSuccess> {
+        const input = decisionRequestSchema.parse(request);
+        const payload = await this.#request<unknown>('POST', '/v1/decisions', {
+            body: input,
+            bindRequestId: true,
+            signal: options.signal,
+            idempotencyKey: options.idempotencyKey,
+            delegatedUserId: options.delegatedUserId,
+        });
+        const parsed = decisionSuccessSchema.safeParse(payload);
+        if (!parsed.success || parsed.data.model !== input.model ||
+            !decisionAnswersMatch(input, parsed.data.data)) {
+            throw new OxyInferenceProtocolError('Invalid or mismatched decisions response.');
+        }
+        return parsed.data;
+    }
+
     /** Generate audio bytes through Oxy's authenticated inference edge. */
     async speech(
         request: OxySpeechRequest,
@@ -665,12 +692,22 @@ export class OxyInferenceClient {
      */
     async getGeneration(
         id: string,
-        options: { signal?: AbortSignal } = {},
+        options: { signal?: AbortSignal; delegatedUserId?: string } = {},
     ): Promise<OxyGenerationReceipt> {
-        const body = await this.#request<{ data: OxyGenerationReceipt }>(
-            'GET',
-            `/v1/generations/${encodeURIComponent(id)}`,
-            { ...(options.signal === undefined ? {} : { signal: options.signal }) },
+        const record = await this.getGenerationRecord(id, options);
+        if (record.schemaVersion !== 1) {
+            throw new OxyInferenceProtocolError('Internal usage has no financial receipt. Use getGenerationRecord().', record.requestId);
+        }
+        return record;
+    }
+
+    /** Read a financial receipt (v1) or an internal technical record (v2). */
+    async getGenerationRecord(
+        id: string,
+        options: { signal?: AbortSignal; delegatedUserId?: string } = {},
+    ): Promise<OxyGenerationRecord> {
+        const body = await this.#request<{ data: OxyGenerationRecord }>(
+            'GET', `/v1/generations/${encodeURIComponent(id)}`, options,
         );
         return body.data;
     }
@@ -728,6 +765,7 @@ export class OxyInferenceClient {
         path: string,
         options: {
             body?: unknown;
+            bindRequestId?: boolean;
             signal?: AbortSignal;
             idempotencyKey?: string;
             delegatedUserId?: string;
@@ -758,6 +796,13 @@ export class OxyInferenceClient {
             );
         }
 
+        if (options.bindRequestId) {
+            const requestId = response.headers.get('X-Oxy-Request-Id');
+            if (!requestId || typeof payload !== 'object' || payload === null ||
+                !('requestId' in payload) || payload.requestId !== requestId) {
+                throw new OxyInferenceProtocolError('Decisions response request ID does not match its header.', requestId ?? undefined);
+            }
+        }
         return payload as T;
     }
 }

package/src/inference/index.ts

@@ -22,6 +22,7 @@ export {
 } from './OxyInferenceClient';
 export type {
   OxyGenerationReceipt,
+  OxyGenerationRecord,
   OxyInferenceClientOptions,
   OxyInferenceCredential,
   OxyInferenceFetch,