samsar-js 0.48.20 → 0.48.21

package/README.md

@@ -512,7 +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`.
+- 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
@@ -556,6 +556,21 @@ 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

@@ -3,6 +3,8 @@ type QueryValue = string | number | boolean | null | undefined;
 type QueryParams = Record<string, QueryValue>;
 export interface SamsarClientOptions {
     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;
 }
@@ -1365,6 +1369,50 @@ export interface V2UserTokenResponse {
     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;
@@ -1572,6 +1620,8 @@ export declare class SamsarRequestError extends Error {
 }
 export declare class SamsarClient {
     private readonly apiKey?;
+    private readonly appKey?;
+    private readonly appSecret?;
     private readonly baseUrl;
     private readonly timeoutMs;
     private readonly fetchFn;
@@ -1600,6 +1650,10 @@ export declare class SamsarClient {
     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;

package/dist/index.js

@@ -271,6 +271,8 @@ function normalizeSessionPublicationInput(input, context) {
 export class SamsarClient {
     constructor(options) {
         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;
@@ -359,6 +361,44 @@ export class SamsarClient {
     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 ?? {}),
@@ -1686,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: this.apiKey ? `Bearer ${this.apiKey}` : undefined,
+            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.20",
+  "version": "0.48.21",
   "description": "TypeScript client for the Samsar Processor API routes.",
   "type": "module",
   "main": "dist/index.js",