samsar-js 0.48.0 → 0.48.2

package/README.md

@@ -4,9 +4,22 @@ TypeScript/ESM client for the Samsar Processor public API (`https://api.samsar.o
 
 ## Installation
 
+Requires Node.js `>=18`.
+
 ```bash
 npm install samsar-js
-# or from a private registry
+```
+
+```bash
+yarn add samsar-js
+```
+
+```bash
+pnpm add samsar-js
+```
+
+```bash
+# optional: install from a private registry mirror
 npm install samsar-js --registry <your-registry-url>
 ```
 
@@ -142,6 +155,23 @@ const images = await samsar.extendImageList({
   num_images: 4,
 });
 
+// Create a reusable receipt template from one sample receipt image (free endpoint)
+const receiptTemplate = await samsar.createReceiptTemplate({
+  image_url: 'https://example.com/receipt-template.png',
+  template_name: 'kbank-transfer-template',
+});
+
+// Fetch the structured template JSON for a saved template (free endpoint)
+const receiptTemplateJson = await samsar.getReceiptTemplateJson(receiptTemplate.data.template_id);
+console.log(receiptTemplateJson.data.template_json);
+
+// Query a new receipt against the saved template (50 credits/request)
+const receiptResult = await samsar.queryReceiptTemplate({
+  image_url: 'https://example.com/receipt-instance.png',
+  template_id: receiptTemplate.data.template_id,
+});
+console.log(receiptResult.data.receipt_json, receiptResult.creditsCharged);
+
 // Enhance low-res images (if needed) and generate a roll-up banner
 const rollup = await samsar.enhanceAndGenerateRollupBanner({
   images: [
@@ -195,6 +225,7 @@ console.log(paymentStatus.data.status);
 ```
 
 Video model support notes:
+- `createVideoFromText` image model keys include: `GPTIMAGE1`, `IMAGEN4`, `SEEDREAM`, `HUNYUAN`, `NANOBANANA2`.
 - `createVideoFromText` supports all express video models: `RUNWAYML`, `KLINGIMGTOVID3PRO`, `HAILUO`, `HAILUOPRO`, `SEEDANCEI2V`, `VEO3.1I2V`, `VEO3.1I2VFAST`, `SORA2`, `SORA2PRO`.
 - `createVideoFromImageList` uses a fixed Veo2.1 pipeline model (`VEO3.1I2V`) and does not accept a `video_model` override.
 
@@ -204,6 +235,7 @@ Each method returns `{ data, status, headers, creditsCharged, creditsRemaining,
 
 - Embedding endpoints (`createEmbedding`, `updateEmbedding`, `searchAgainstEmbedding`, `similarToEmbedding`) are billed by input tokens at $1 per million tokens. `deleteEmbeddings` does not consume tokens.
 - Token counts follow OpenAI tokenization for `text-embedding-3-large`. Credit deductions follow the existing 100 credits per USD rule.
+- Receipt template creation (`createReceiptTemplate`) and template JSON lookup (`getReceiptTemplateJson`) are free; receipt template query (`queryReceiptTemplate`) costs 50 credits per request.
 
 ## Configuration
 
@@ -231,3 +263,17 @@ npm publish --registry <your-registry-url>
 ```
 
 Ensure `package.json` name/version are set as desired before publishing.
+
+## Maintainer Deploy Script
+
+`deploy.sh` publishes the current package to npm using `NPM_TOKEN` from env (or `.env`).
+
+```bash
+# publish current version
+./deploy.sh
+
+# bump version, then publish
+./deploy.sh patch
+./deploy.sh minor
+./deploy.sh major
+```

package/dist/index.d.ts

@@ -534,6 +534,98 @@ export interface ExtendImageListResponse {
     remainingCredits?: number;
     [key: string]: unknown;
 }
+export interface ReceiptTemplateRoi {
+    id: string;
+    label: string;
+    purpose?: string | null;
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface ReceiptTemplateField {
+    key: string;
+    label: string;
+    type: string;
+    required: boolean;
+    roi_id?: string | null;
+    description?: string | null;
+}
+export interface ReceiptTemplateDefinition {
+    schema_version?: string;
+    merchant_hint?: string | null;
+    language_hint?: string | null;
+    currency_hint?: string | null;
+    rois?: ReceiptTemplateRoi[];
+    fields?: ReceiptTemplateField[];
+    validation_rules?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface CreateReceiptTemplateRequest {
+    image_url?: string;
+    imageUrl?: string;
+    receipt_url?: string;
+    receiptUrl?: string;
+    template_url?: string;
+    templateUrl?: string;
+    template_name?: string;
+    templateName?: string;
+}
+export interface CreateReceiptTemplateResponse {
+    template_id: string;
+    template_hash?: string;
+    template_name?: string | null;
+    normalized_template?: ReceiptTemplateDefinition;
+    sample_receipt?: Record<string, unknown>;
+    created_at?: string;
+    [key: string]: unknown;
+}
+export interface QueryReceiptTemplateRequest {
+    image_url?: string;
+    imageUrl?: string;
+    receipt_url?: string;
+    receiptUrl?: string;
+    template_id?: string;
+    templateId?: string;
+    receipt_template_id?: string;
+    receiptTemplateId?: string;
+}
+export interface QueryReceiptTemplateResponse {
+    template_id: string;
+    template_hash?: string;
+    template_name?: string | null;
+    normalized_template?: ReceiptTemplateDefinition;
+    receipt_json?: Record<string, unknown>;
+    standardized_receipt?: Record<string, unknown>;
+    items?: Array<Record<string, unknown>>;
+    unreadable_fields?: string[];
+    confidence?: number;
+    validation?: {
+        is_valid?: boolean;
+        issues?: string[];
+        missing_required_fields?: string[];
+        type_mismatch_fields?: string[];
+        arithmetic?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    attempts?: number;
+    creditsCharged?: number;
+    remainingCredits?: number | null;
+    [key: string]: unknown;
+}
+export interface GetReceiptTemplateJsonResponse {
+    template_id: string;
+    template_hash?: string;
+    template_name?: string | null;
+    source_image_url?: string | null;
+    normalized_template?: ReceiptTemplateDefinition;
+    template_json?: ReceiptTemplateDefinition;
+    sample_receipt?: Record<string, unknown>;
+    provider?: Record<string, unknown> | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+    [key: string]: unknown;
+}
 export interface RollupBannerOverlay {
     footer?: string | null;
     bottom?: string | null;
@@ -919,6 +1011,20 @@ export declare class SamsarClient {
      * Add or extend a saved image list for the authenticated API key.
      */
     extendImageList(payload: ExtendImageListRequest, options?: SamsarRequestOptions): Promise<SamsarResult<ExtendImageListResponse>>;
+    /**
+     * Create and save a reusable receipt extraction template from a sample receipt image.
+     * This endpoint is free and does not deduct credits.
+     */
+    createReceiptTemplate(payload: CreateReceiptTemplateRequest, options?: SamsarRequestOptions): Promise<SamsarResult<CreateReceiptTemplateResponse>>;
+    /**
+     * Extract standardized receipt JSON by validating a receipt image against a saved template.
+     * This endpoint charges 50 credits per request.
+     */
+    queryReceiptTemplate(payload: QueryReceiptTemplateRequest, options?: SamsarRequestOptions): Promise<SamsarResult<QueryReceiptTemplateResponse>>;
+    /**
+     * Fetch the structured template JSON for a template id that belongs to the authenticated API key.
+     */
+    getReceiptTemplateJson(templateId: string, options?: SamsarRequestOptions): Promise<SamsarResult<GetReceiptTemplateJsonResponse>>;
     /**
      * Create a roll-up banner from preprocessed (already enhanced) images.
      */

package/dist/index.js

@@ -590,6 +590,82 @@ export class SamsarClient {
     async extendImageList(payload, options) {
         return this.post('image/add_image_set', payload, options);
     }
+    /**
+     * Create and save a reusable receipt extraction template from a sample receipt image.
+     * This endpoint is free and does not deduct credits.
+     */
+    async createReceiptTemplate(payload, options) {
+        const raw = payload;
+        const imageUrl = (typeof raw.image_url === 'string' && raw.image_url.trim()) ||
+            (typeof raw.imageUrl === 'string' && raw.imageUrl.trim()) ||
+            (typeof raw.receipt_url === 'string' && raw.receipt_url.trim()) ||
+            (typeof raw.receiptUrl === 'string' && raw.receiptUrl.trim()) ||
+            (typeof raw.template_url === 'string' && raw.template_url.trim()) ||
+            (typeof raw.templateUrl === 'string' && raw.templateUrl.trim()) ||
+            null;
+        if (!imageUrl) {
+            throw new Error('image_url (or receipt_url/template_url) is required');
+        }
+        const templateName = (typeof raw.template_name === 'string' && raw.template_name.trim()) ||
+            (typeof raw.templateName === 'string' && raw.templateName.trim()) ||
+            undefined;
+        const requestPayload = {
+            ...payload,
+            image_url: imageUrl,
+            receipt_url: imageUrl,
+            template_url: imageUrl,
+            ...(templateName ? { template_name: templateName } : {}),
+        };
+        return this.post('image/receipt_templates/create', requestPayload, options);
+    }
+    /**
+     * Extract standardized receipt JSON by validating a receipt image against a saved template.
+     * This endpoint charges 50 credits per request.
+     */
+    async queryReceiptTemplate(payload, options) {
+        const raw = payload;
+        const imageUrl = (typeof raw.image_url === 'string' && raw.image_url.trim()) ||
+            (typeof raw.imageUrl === 'string' && raw.imageUrl.trim()) ||
+            (typeof raw.receipt_url === 'string' && raw.receipt_url.trim()) ||
+            (typeof raw.receiptUrl === 'string' && raw.receiptUrl.trim()) ||
+            null;
+        if (!imageUrl) {
+            throw new Error('image_url (or receipt_url) is required');
+        }
+        const templateId = (typeof raw.template_id === 'string' && raw.template_id.trim()) ||
+            (typeof raw.templateId === 'string' && raw.templateId.trim()) ||
+            (typeof raw.receipt_template_id === 'string' && raw.receipt_template_id.trim()) ||
+            (typeof raw.receiptTemplateId === 'string' && raw.receiptTemplateId.trim()) ||
+            null;
+        if (!templateId) {
+            throw new Error('template_id is required');
+        }
+        const requestPayload = {
+            ...payload,
+            image_url: imageUrl,
+            receipt_url: imageUrl,
+            template_id: templateId,
+            receipt_template_id: templateId,
+        };
+        return this.post('image/receipt_templates/query', requestPayload, options);
+    }
+    /**
+     * Fetch the structured template JSON for a template id that belongs to the authenticated API key.
+     */
+    async getReceiptTemplateJson(templateId, options) {
+        const normalizedTemplateId = typeof templateId === 'string' ? templateId.trim() : '';
+        if (!normalizedTemplateId) {
+            throw new Error('templateId is required');
+        }
+        const query = {
+            ...(options?.query ?? {}),
+            template_id: normalizedTemplateId,
+        };
+        return this.get('image/template_json', {
+            ...(options ?? {}),
+            query,
+        });
+    }
     /**
      * Create a roll-up banner from preprocessed (already enhanced) images.
      */

package/package.json

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