samsar-js 0.48.19 → 0.48.21

package/README.md

@@ -512,6 +512,7 @@ Video model support notes:
 Upcoming `/v2` omni route adapters:
 - `/v2` is additive; `/v1` is not deprecated.
 - `createV2VideoFromText`, `createV2VideoFromImageList`, `updateV2VideoOutroImage`, `addV2VideoOutroImage`, `getV2Status`, `getV2Credits`, `listV2Requests`, and `createV2Session` call the new omni route surface.
+- Programmatic user billing helpers include `createV2UserRechargeCredits`, `refreshV2UserToken`, `createV2UserAppKey`, `refreshV2UserAppKey`, `getV2UserCredits`, `getV2UserUsageLogs`, and `getV2UserPaymentStatus`.
 - Omit `externalUser` for internal account billing, pass `externalUser` to scope an external user with the account API key, or authenticate the client directly with an external-user auth token/API key.
 
 ```ts
@@ -535,6 +536,41 @@ const v2Status = await platform.getV2Status(v2Video.data.request_id!);
 console.log(v2Status.data.status);
 ```
 
+Programmatic user recharge and OAuth-style refresh token rotation:
+
+```ts
+const publicClient = new SamsarClient({});
+
+const checkout = await publicClient.createV2UserRechargeCredits({
+  amount: 25,
+  email: 'customer@example.com',
+  redirect_url: 'https://example.com/samsar/callback',
+});
+
+// After the Stripe webhook calls your redirect_url with authToken, refreshToken, and expiryDate:
+const userClient = new SamsarClient({ apiKey: authToken });
+const refreshed = await userClient.refreshV2UserToken(refreshToken);
+
+localStorage.setItem('authToken', refreshed.data.authToken);
+localStorage.setItem('refreshToken', refreshed.data.refreshToken);
+localStorage.setItem('expiryDate', refreshed.data.expiryDate);
+```
+
+Long-running app credentials:
+
+```ts
+const secret = crypto.randomUUID() + crypto.randomUUID();
+const created = await userClient.createV2UserAppKey({ secret });
+
+const appClient = new SamsarClient({
+  appKey: created.data.appKey ?? created.data.app_key,
+  appSecret: secret,
+});
+
+const credits = await appClient.getV2UserCredits();
+const rotated = await appClient.refreshV2UserAppKey();
+```
+
 Each method returns `{ data, status, headers, creditsCharged, creditsRemaining, raw }`. Non-2xx responses throw `SamsarRequestError` containing status, body, and credit headers (if present).
 
 ## Billing notes

package/dist/index.d.ts

@@ -2,7 +2,9 @@ type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Respo
 type QueryValue = string | number | boolean | null | undefined;
 type QueryParams = Record<string, QueryValue>;
 export interface SamsarClientOptions {
-    apiKey: string;
+    apiKey?: string;
+    appKey?: string;
+    appSecret?: string;
     baseUrl?: string;
     timeoutMs?: number;
     fetch?: FetchLike;
@@ -13,6 +15,8 @@ export interface SamsarRequestOptions {
     idempotencyKey?: string;
     headers?: Record<string, string>;
     externalUserApiKey?: string;
+    appKey?: string;
+    appSecret?: string;
     signal?: AbortSignal;
     query?: QueryParams;
 }
@@ -1334,6 +1338,105 @@ export interface V2RequestsListResponse {
     externalUser?: ExternalUserSummary | null;
     [key: string]: unknown;
 }
+export interface V2UserRechargeCreditsRequest {
+    amount: number;
+    email: string;
+    redirect_url?: string;
+    redirectUrl?: string;
+    [key: string]: unknown;
+}
+export interface V2UserRechargeCreditsResponse {
+    url: string;
+    checkoutSessionId?: string | null;
+    paymentStatusEndpoint?: string;
+    amount: number;
+    amountCents: number;
+    credits: number;
+    currency: string;
+    redirectUrl?: string;
+    [key: string]: unknown;
+}
+export interface V2UserTokenRefreshRequest {
+    refreshToken?: string;
+    refresh_token?: string;
+}
+export interface V2UserTokenResponse {
+    tokenType?: 'Bearer' | string;
+    authToken: string;
+    refreshToken: string;
+    expiryDate: string;
+    expiresInSeconds?: number;
+    refreshTokenExpiresAt?: string;
+    [key: string]: unknown;
+}
+export interface V2UserAppKeyRequest {
+    secret?: string;
+    appSecret?: string;
+    app_secret?: string;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface V2UserAppKeyRefreshRequest {
+    appKey?: string;
+    app_key?: string;
+    secret?: string;
+    appSecret?: string;
+    app_secret?: string;
+    [key: string]: unknown;
+}
+export interface V2UserAppKeyRecord {
+    id?: string;
+    userId?: string;
+    appKeyPrefix?: string | null;
+    appKeyLast4?: string | null;
+    status?: 'active' | 'revoked' | string;
+    expiresAt?: string | null;
+    lastUsedAt?: string | null;
+    refreshedAt?: string | null;
+    revokedAt?: string | null;
+    rotationCount?: number;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    authScheme?: string;
+    authHeader?: string;
+    secretHeader?: string;
+    [key: string]: unknown;
+}
+export interface V2UserAppKeyResponse {
+    app_key?: string;
+    appKey?: string;
+    token_type?: 'AppKey' | string;
+    tokenType?: 'AppKey' | string;
+    expires_at?: string;
+    expiresAt?: string;
+    app_key_record?: V2UserAppKeyRecord;
+    appKeyRecord?: V2UserAppKeyRecord;
+    [key: string]: unknown;
+}
+export interface UsageLogItem {
+    id?: string;
+    source?: string;
+    credits?: number;
+    balanceAfter?: number | null;
+    metadata?: Record<string, unknown>;
+    direction?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+export interface UsageLogsResponse {
+    items: UsageLogItem[];
+    pagination?: {
+        page?: number;
+        pageSize?: number;
+        totalItems?: number;
+        totalPages?: number;
+        hasNextPage?: boolean;
+        hasPreviousPage?: boolean;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
 export interface ExternalArchiveResponse {
     request?: ExternalRequestSummary | null;
     external_user?: ExternalUserSummary | null;
@@ -1516,7 +1619,9 @@ export declare class SamsarRequestError extends Error {
     constructor(message: string, init: SamsarErrorInit);
 }
 export declare class SamsarClient {
-    private readonly apiKey;
+    private readonly apiKey?;
+    private readonly appKey?;
+    private readonly appSecret?;
     private readonly baseUrl;
     private readonly timeoutMs;
     private readonly fetchFn;
@@ -1535,7 +1640,21 @@ export declare class SamsarClient {
     getV2<T = Record<string, unknown>>(path: string, options?: V2RequestOptions): Promise<SamsarResult<T>>;
     createV2Session(options?: V2RequestOptions): Promise<SamsarResult<V2SessionResponse>>;
     getV2Credits(options?: V2RequestOptions): Promise<SamsarResult<CreditsBalanceResponse | ExternalCreditsBalanceResponse>>;
+    getV2UserCredits(options?: V2RequestOptions): Promise<SamsarResult<CreditsBalanceResponse>>;
+    getV2UserUsageLogs(options?: V2RequestOptions & {
+        page?: number;
+        pageSize?: number;
+        limit?: number;
+    }): Promise<SamsarResult<UsageLogsResponse>>;
     listV2Requests(options?: V2RequestOptions): Promise<SamsarResult<V2RequestsListResponse>>;
+    createV2UserRechargeCredits(payload: V2UserRechargeCreditsRequest, options?: V2RequestOptions): Promise<SamsarResult<V2UserRechargeCreditsResponse>>;
+    refreshV2UserToken(payload: string | V2UserTokenRefreshRequest, options?: V2RequestOptions): Promise<SamsarResult<V2UserTokenResponse>>;
+    refreshV2UserAuthToken(payload: string | V2UserTokenRefreshRequest, options?: V2RequestOptions): Promise<SamsarResult<V2UserTokenResponse>>;
+    createV2UserAppKey(payload: string | V2UserAppKeyRequest, options?: V2RequestOptions): Promise<SamsarResult<V2UserAppKeyResponse>>;
+    getV2UserAppKey(options?: V2RequestOptions): Promise<SamsarResult<V2UserAppKeyResponse>>;
+    refreshV2UserAppKey(payload?: V2UserAppKeyRefreshRequest, options?: V2RequestOptions): Promise<SamsarResult<V2UserAppKeyResponse>>;
+    revokeV2UserAppKey(options?: V2RequestOptions): Promise<SamsarResult<V2UserAppKeyResponse>>;
+    getV2UserPaymentStatus(payload: PaymentStatusRequest, options?: V2RequestOptions): Promise<SamsarResult<PaymentStatusResponse>>;
     createV2LoginToken(options?: V2RequestOptions & {
         redirect?: string;
     }): Promise<SamsarResult<CreateLoginTokenResponse | ExternalCreateLoginTokenResponse>>;

package/dist/index.js

@@ -270,10 +270,9 @@ function normalizeSessionPublicationInput(input, context) {
 }
 export class SamsarClient {
     constructor(options) {
-        if (!options?.apiKey) {
-            throw new Error('apiKey is required to initialize SamsarClient');
-        }
-        this.apiKey = options.apiKey;
+        this.apiKey = options?.apiKey?.trim() || undefined;
+        this.appKey = options?.appKey?.trim() || undefined;
+        this.appSecret = options?.appSecret?.trim() || undefined;
         this.baseUrl = trimTrailingSlash(options.baseUrl ?? DEFAULT_BASE_URL);
         this.timeoutMs = options.timeoutMs ?? 30000;
         this.fetchFn = options.fetch ?? globalThis.fetch;
@@ -307,9 +306,117 @@ export class SamsarClient {
     async getV2Credits(options) {
         return this.getV2('credits', options);
     }
+    async getV2UserCredits(options) {
+        return this.getV2('user/credits', options);
+    }
+    async getV2UserUsageLogs(options) {
+        const query = {
+            ...(options?.query ?? {}),
+        };
+        if (options?.page !== undefined) {
+            query.page = options.page;
+        }
+        if (options?.pageSize !== undefined) {
+            query.pageSize = options.pageSize;
+        }
+        if (options?.limit !== undefined) {
+            query.limit = options.limit;
+        }
+        return this.getV2('user/usage/logs', {
+            ...(options ?? {}),
+            query,
+        });
+    }
     async listV2Requests(options) {
         return this.getV2('requests', options);
     }
+    async createV2UserRechargeCredits(payload, options) {
+        const amount = Number(payload?.amount);
+        if (!Number.isFinite(amount) || amount <= 0) {
+            throw new Error('amount must be a positive dollar amount');
+        }
+        if (!payload?.email || typeof payload.email !== 'string') {
+            throw new Error('email is required');
+        }
+        const redirectUrl = payload.redirect_url ?? payload.redirectUrl;
+        if (!redirectUrl || typeof redirectUrl !== 'string') {
+            throw new Error('redirect_url is required');
+        }
+        return this.postV2('user/recharge_credits', {
+            ...payload,
+            amount,
+            email: payload.email.trim(),
+            redirect_url: redirectUrl.trim(),
+        }, options);
+    }
+    async refreshV2UserToken(payload, options) {
+        const refreshToken = typeof payload === 'string'
+            ? payload
+            : (payload?.refreshToken ?? payload?.refresh_token);
+        if (!refreshToken || typeof refreshToken !== 'string') {
+            throw new Error('refreshToken is required');
+        }
+        return this.postV2('user/refresh_token', { refreshToken: refreshToken.trim() }, options);
+    }
+    async refreshV2UserAuthToken(payload, options) {
+        return this.refreshV2UserToken(payload, options);
+    }
+    async createV2UserAppKey(payload, options) {
+        const input = typeof payload === 'string' ? { secret: payload } : (payload ?? {});
+        const secret = input.secret ?? input.appSecret ?? input.app_secret;
+        if (!secret || typeof secret !== 'string') {
+            throw new Error('secret is required');
+        }
+        if (secret.trim().length < 32) {
+            throw new Error('secret must be at least 32 characters');
+        }
+        return this.postV2('users/app_key', {
+            ...input,
+            secret: secret.trim(),
+        }, options);
+    }
+    async getV2UserAppKey(options) {
+        return this.getV2('users/app_key', options);
+    }
+    async refreshV2UserAppKey(payload, options) {
+        const input = payload ?? {};
+        const appKey = input.appKey ?? input.app_key ?? options?.appKey ?? this.appKey;
+        const secret = input.secret ?? input.appSecret ?? input.app_secret ?? options?.appSecret ?? this.appSecret;
+        if (!appKey || typeof appKey !== 'string') {
+            throw new Error('appKey is required');
+        }
+        if (!secret || typeof secret !== 'string') {
+            throw new Error('secret is required');
+        }
+        if (secret.trim().length < 32) {
+            throw new Error('secret must be at least 32 characters');
+        }
+        return this.postV2('users/app_key/refresh', {
+            app_key: appKey.trim(),
+            secret: secret.trim(),
+        }, options);
+    }
+    async revokeV2UserAppKey(options) {
+        return this.request(this.buildV2Url('users/app_key'), { ...(options ?? {}), method: 'DELETE' });
+    }
+    async getV2UserPaymentStatus(payload, options) {
+        const query = {
+            ...(options?.query ?? {}),
+        };
+        if (payload?.checkoutSessionId) {
+            query.checkoutSessionId = payload.checkoutSessionId;
+        }
+        if (payload?.paymentIntentId) {
+            query.paymentIntentId = payload.paymentIntentId;
+        }
+        if (payload?.setupIntentId) {
+            query.setupIntentId = payload.setupIntentId;
+        }
+        return this.getV2('user/payment_status', {
+            ...(options ?? {}),
+            query,
+        });
+    }
     async createV2LoginToken(options) {
         const body = options?.redirect ? { redirect: options.redirect } : {};
         return this.postV2('create_login_token', body, options);
@@ -1619,10 +1726,17 @@ export class SamsarClient {
         };
     }
     buildHeaders(options) {
+        const resolvedAppKey = options.appKey?.trim() || (!this.apiKey ? this.appKey : undefined);
+        const resolvedAppSecret = options.appSecret?.trim() || this.appSecret;
         const headers = {
-            Authorization: `Bearer ${this.apiKey}`,
+            Authorization: resolvedAppKey
+                ? `AppKey ${resolvedAppKey}`
+                : this.apiKey
+                    ? `Bearer ${this.apiKey}`
+                    : undefined,
             'Content-Type': options.body ? 'application/json' : undefined,
             'x-external-user-api-key': options.externalUserApiKey ?? this.externalUserApiKey,
+            'x-app-secret': resolvedAppKey ? resolvedAppSecret : undefined,
             ...this.defaultHeaders,
             ...(options.headers ?? {}),
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "samsar-js",
-  "version": "0.48.19",
+  "version": "0.48.21",
   "description": "TypeScript client for the Samsar Processor API routes.",
   "type": "module",
   "main": "dist/index.js",