samsar-js 0.48.19 → 0.48.20

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`, `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,26 @@ 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);
+```
+
 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,7 @@ 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;
     baseUrl?: string;
     timeoutMs?: number;
     fetch?: FetchLike;
@@ -1334,6 +1334,61 @@ 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 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 +1571,7 @@ export declare class SamsarRequestError extends Error {
     constructor(message: string, init: SamsarErrorInit);
 }
 export declare class SamsarClient {
-    private readonly apiKey;
+    private readonly apiKey?;
     private readonly baseUrl;
     private readonly timeoutMs;
     private readonly fetchFn;
@@ -1535,7 +1590,17 @@ 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>>;
+    getV2UserPaymentStatus(payload: PaymentStatusRequest, options?: V2RequestOptions): Promise<SamsarResult<PaymentStatusResponse>>;
     createV2LoginToken(options?: V2RequestOptions & {
         redirect?: string;
     }): Promise<SamsarResult<CreateLoginTokenResponse | ExternalCreateLoginTokenResponse>>;

package/dist/index.js

@@ -270,10 +270,7 @@ 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.baseUrl = trimTrailingSlash(options.baseUrl ?? DEFAULT_BASE_URL);
         this.timeoutMs = options.timeoutMs ?? 30000;
         this.fetchFn = options.fetch ?? globalThis.fetch;
@@ -307,9 +304,79 @@ 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 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);
@@ -1620,7 +1687,7 @@ export class SamsarClient {
     }
     buildHeaders(options) {
         const headers = {
-            Authorization: `Bearer ${this.apiKey}`,
+            Authorization: this.apiKey ? `Bearer ${this.apiKey}` : undefined,
             'Content-Type': options.body ? 'application/json' : undefined,
             'x-external-user-api-key': options.externalUserApiKey ?? this.externalUserApiKey,
             ...this.defaultHeaders,

package/package.json

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