@proveanything/smartlinks 1.0.40 → 1.0.42

package/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.0.40  |  Generated: 2025-11-09T13:05:52.500Z
+Version: 1.0.42  |  Generated: 2025-11-18T13:09:06.423Z
 
 This is a concise summary of all available API functions and types.
 
@@ -17,6 +17,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **batch** - Product batch management and tracking
 - **claimSet** - Claim creation, management, and verification
 - **collection** - Collection CRUD operations and management
+- **comms** - Functions for comms operations
 - **crate** - Container/crate management for organizing products
 - **form** - Dynamic form creation and submission
 - **product** - Product CRUD operations and management within collections
@@ -221,6 +222,92 @@ interface CollectionResponse {
 }
 ```
 
+### comms
+
+**NotificationSubjectTarget** (interface)
+```typescript
+interface NotificationSubjectTarget {
+  type: 'product' | 'collection' | 'user' | 'batch' | 'proof'
+  id: string
+}
+```
+
+**PushNotificationTemplate** (interface)
+```typescript
+interface PushNotificationTemplate {
+  title: string
+  body: string
+  icon?: string
+}
+```
+
+**EmailNotificationTemplate** (interface)
+```typescript
+interface EmailNotificationTemplate {
+  subject: string
+  body: string
+}
+```
+
+**WalletUpdateTemplate** (interface)
+```typescript
+interface WalletUpdateTemplate {
+  textModulesData?: Array<{
+  id: string
+  header: string
+  body: string
+  }>
+}
+```
+
+**NotificationTemplate** (interface)
+```typescript
+interface NotificationTemplate {
+  push?: PushNotificationTemplate
+  email?: EmailNotificationTemplate
+  walletUpdate?: WalletUpdateTemplate
+}
+```
+
+**SendNotificationRequest** (interface)
+```typescript
+interface SendNotificationRequest {
+  subjectTargets: NotificationSubjectTarget[]
+  severity: 'low' | 'normal' | 'important' | 'critical'
+  mode: 'preferred' | 'all'
+  channels : ("push" | "email" | "wallet")[]
+  template: NotificationTemplate
+}
+```
+
+**SendNotificationResponse** (interface)
+```typescript
+interface SendNotificationResponse {
+  ok: boolean
+  notificationId: string
+  counts: {
+  contacts: number
+  attempts: number
+  }
+  status: {
+  notification: {
+  notificationId: string
+  state: 'queued' | 'sent' | 'failed' | 'confirmed' | string
+  subjectTargets: NotificationSubjectTarget[]
+  severity: 'low' | 'normal' | 'important' | 'critical' | string
+  channelsOverride: Record<string, any>
+  template: NotificationTemplate
+  }
+  totals: {
+  queued: number
+  sent: number
+  failed: number
+  confirmed: number
+  }
+  }
+}
+```
+
 ### error
 
 **ErrorResponse** (interface)
@@ -678,6 +765,12 @@ Look up a serial number by code for a collection (admin only).
     value: any) → `Promise<any>`
 Assign a value to a serial number for a collection (admin only).
 
+### comms
+
+**sendNotification**(collectionId: string,
+    request: SendNotificationRequest) → `Promise<SendNotificationResponse>`
+Send a notification to specified targets within a collection. Supports multiple delivery methods including push notifications, email, and wallet pass updates. The notification will be delivered based on user preferences and the specified delivery mode. ```typescript const result = await comms.sendNotification('my-collection', { subjectTargets: [{ type: 'product', id: 'prod_123' }], severity: 'important', mode: 'preferred', template: { push: { title: 'Update available', body: 'We\'ve shipped an important update.', icon: 'https://cdn.example.com/brand/logo-128.png' }, email: { subject: 'Important update for your product', body: 'There\'s an important update. Open your pass or profile to learn more.' }, walletUpdate: { textModulesData: [ { id: 'notice', header: 'Update', body: 'Open your wallet pass for details.' } ] } } }) if (result.ok) { console.log('Notification queued:', result.notificationId) console.log('Totals:', result.status.totals) } ```
+
 ### crate
 
 **get**(collectionId: string, crateId: string) → `Promise<any>`
@@ -752,10 +845,12 @@ Look up a serial number by code for a product (admin only).
 **get**(collectionId: string,
     productId: string,
     proofId: string,
-    admin?: boolean) → `Promise<ProofResponse>`
+    admin?: boolean,
+    include?: string[]) → `Promise<ProofResponse>`
 Retrieves a single Proof by Collection ID, Product ID, and Proof ID. Both public and admin endpoints now include productId in the path.
 
-**list**(collectionId: string) → `Promise<ProofResponse[]>`
+**list**(collectionId: string,
+    include?: string[]) → `Promise<ProofResponse[]>`
 List all Proofs for a Collection.
 
 **create**(collectionId: string,

package/dist/api/comms.d.ts

@@ -0,0 +1,47 @@
+import type { SendNotificationRequest, SendNotificationResponse } from "../types/comms";
+/**
+ * Communications namespace for sending notifications and managing user communications
+ */
+export declare namespace comms {
+    /**
+     * Send a notification to specified targets within a collection.
+     *
+     * Supports multiple delivery methods including push notifications, email, and wallet pass updates.
+     * The notification will be delivered based on user preferences and the specified delivery mode.
+     *
+     * @param collectionId - ID of the collection containing the notification targets
+     * @param request - Notification configuration including targets, severity, and content templates
+    * @returns Promise resolving to the notification enqueue/queue status and totals
+     * @throws ErrorResponse if the request fails or targets are invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await comms.sendNotification('my-collection', {
+     *   subjectTargets: [{ type: 'product', id: 'prod_123' }],
+     *   severity: 'important',
+     *   mode: 'preferred',
+     *   template: {
+     *     push: {
+     *       title: 'Update available',
+     *       body: 'We\'ve shipped an important update.',
+     *       icon: 'https://cdn.example.com/brand/logo-128.png'
+     *     },
+     *     email: {
+     *       subject: 'Important update for your product',
+     *       body: 'There\'s an important update. Open your pass or profile to learn more.'
+     *     },
+     *     walletUpdate: {
+     *       textModulesData: [
+     *         { id: 'notice', header: 'Update', body: 'Open your wallet pass for details.' }
+     *       ]
+     *     }
+     *   }
+     * })
+     * if (result.ok) {
+     *   console.log('Notification queued:', result.notificationId)
+     *   console.log('Totals:', result.status.totals)
+     * }
+     * ```
+     */
+    function sendNotification(collectionId: string, request: SendNotificationRequest): Promise<SendNotificationResponse>;
+}

package/dist/api/comms.js

@@ -0,0 +1,54 @@
+// src/api/comms.ts
+// Communications and notifications API for Smartlinks
+import { post } from "../http";
+/**
+ * Communications namespace for sending notifications and managing user communications
+ */
+export var comms;
+(function (comms) {
+    /**
+     * Send a notification to specified targets within a collection.
+     *
+     * Supports multiple delivery methods including push notifications, email, and wallet pass updates.
+     * The notification will be delivered based on user preferences and the specified delivery mode.
+     *
+     * @param collectionId - ID of the collection containing the notification targets
+     * @param request - Notification configuration including targets, severity, and content templates
+    * @returns Promise resolving to the notification enqueue/queue status and totals
+     * @throws ErrorResponse if the request fails or targets are invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await comms.sendNotification('my-collection', {
+     *   subjectTargets: [{ type: 'product', id: 'prod_123' }],
+     *   severity: 'important',
+     *   mode: 'preferred',
+     *   template: {
+     *     push: {
+     *       title: 'Update available',
+     *       body: 'We\'ve shipped an important update.',
+     *       icon: 'https://cdn.example.com/brand/logo-128.png'
+     *     },
+     *     email: {
+     *       subject: 'Important update for your product',
+     *       body: 'There\'s an important update. Open your pass or profile to learn more.'
+     *     },
+     *     walletUpdate: {
+     *       textModulesData: [
+     *         { id: 'notice', header: 'Update', body: 'Open your wallet pass for details.' }
+     *       ]
+     *     }
+     *   }
+     * })
+     * if (result.ok) {
+     *   console.log('Notification queued:', result.notificationId)
+     *   console.log('Totals:', result.status.totals)
+     * }
+     * ```
+     */
+    async function sendNotification(collectionId, request) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/comm/notify`;
+        return post(path, request);
+    }
+    comms.sendNotification = sendNotification;
+})(comms || (comms = {}));

package/dist/api/index.d.ts

@@ -12,4 +12,5 @@ export { crate } from "./crate";
 export { batch } from "./batch";
 export { variant } from "./variant";
 export { ai } from "./ai";
+export { comms } from "./comms";
 export type { AIGenerateContentRequest, AIGenerateImageRequest, AISearchPhotosRequest, AISearchPhotosPhoto } from "./ai";

package/dist/api/index.js

@@ -14,3 +14,4 @@ export { crate } from "./crate";
 export { batch } from "./batch";
 export { variant } from "./variant";
 export { ai } from "./ai";
+export { comms } from "./comms";

package/dist/api/proof.d.ts

@@ -4,11 +4,11 @@ export declare namespace proof {
      * Retrieves a single Proof by Collection ID, Product ID, and Proof ID.
      * Both public and admin endpoints now include productId in the path.
      */
-    function get(collectionId: string, productId: string, proofId: string, admin?: boolean): Promise<ProofResponse>;
+    function get(collectionId: string, productId: string, proofId: string, admin?: boolean, include?: string[]): Promise<ProofResponse>;
     /**
      * List all Proofs for a Collection.
      */
-    function list(collectionId: string): Promise<ProofResponse[]>;
+    function list(collectionId: string, include?: string[]): Promise<ProofResponse[]>;
     /**
      * Create a proof for a product (admin only).
      * POST /admin/collection/:collectionId/product/:productId/proof

package/dist/api/proof.js

@@ -6,17 +6,19 @@ export var proof;
      * Retrieves a single Proof by Collection ID, Product ID, and Proof ID.
      * Both public and admin endpoints now include productId in the path.
      */
-    async function get(collectionId, productId, proofId, admin) {
+    async function get(collectionId, productId, proofId, admin, include) {
         const base = admin ? '/admin' : '/public';
-        const path = `${base}/collection/${encodeURIComponent(collectionId)}/product/${encodeURIComponent(productId)}/proof/${encodeURIComponent(proofId)}`;
+        const qp = include && include.length ? `?include=${encodeURIComponent(include.join(','))}` : '';
+        const path = `${base}/collection/${encodeURIComponent(collectionId)}/product/${encodeURIComponent(productId)}/proof/${encodeURIComponent(proofId)}${qp}`;
         return request(path);
     }
     proof.get = get;
     /**
      * List all Proofs for a Collection.
      */
-    async function list(collectionId) {
-        const path = `/public/collection/${encodeURIComponent(collectionId)}/proof`;
+    async function list(collectionId, include) {
+        const qp = include && include.length ? `?include=${encodeURIComponent(include.join(','))}` : '';
+        const path = `/public/collection/${encodeURIComponent(collectionId)}/proof${qp}`;
         return request(path);
     }
     proof.list = list;

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from "./api";
 export * from "./types";
 export type { LoginResponse, VerifyTokenResponse, AccountInfoResponse, } from "./api/auth";
 export type { UserAccountRegistrationRequest, } from "./types/auth";
+export type { SendNotificationRequest, SendNotificationResponse, NotificationSubjectTarget, NotificationTemplate, PushNotificationTemplate, EmailNotificationTemplate, WalletUpdateTemplate, } from "./types/comms";
 export type { AttestationResponse, AttestationCreateRequest, AttestationUpdateRequest, } from "./types/attestation";
 export type { BatchResponse, BatchCreateRequest, BatchUpdateRequest, } from "./types/batch";
 export type { VariantResponse, VariantCreateRequest, VariantUpdateRequest, } from "./types/variant";

package/dist/types/comms.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Target subject for notifications (product, collection, etc.)
+ */
+export interface NotificationSubjectTarget {
+    /** Type of target entity */
+    type: 'product' | 'collection' | 'user' | 'batch' | 'proof';
+    /** ID of the target entity */
+    id: string;
+}
+/**
+ * Push notification template content
+ */
+export interface PushNotificationTemplate {
+    /** Notification title */
+    title: string;
+    /** Notification body text */
+    body: string;
+    /** Optional icon URL for the notification */
+    icon?: string;
+}
+/**
+ * Email notification template content
+ */
+export interface EmailNotificationTemplate {
+    /** Email subject line */
+    subject: string;
+    /** Email body content (plain text or HTML) */
+    body: string;
+}
+/**
+ * Wallet pass update template content
+ */
+export interface WalletUpdateTemplate {
+    /** Text modules to update in the wallet pass */
+    textModulesData?: Array<{
+        /** Module ID */
+        id: string;
+        /** Module header text */
+        header: string;
+        /** Module body text */
+        body: string;
+    }>;
+}
+/**
+ * Notification template containing different delivery methods
+ */
+export interface NotificationTemplate {
+    /** Push notification content */
+    push?: PushNotificationTemplate;
+    /** Email notification content */
+    email?: EmailNotificationTemplate;
+    /** Wallet pass update content */
+    walletUpdate?: WalletUpdateTemplate;
+}
+/**
+ * Request payload for sending notifications
+ */
+export interface SendNotificationRequest {
+    /** Target subjects that should receive the notification */
+    subjectTargets: NotificationSubjectTarget[];
+    /** Severity level of the notification */
+    severity: 'low' | 'normal' | 'important' | 'critical';
+    /** Delivery chanell mode preference */
+    mode: 'preferred' | 'all';
+    /** Specific channels to use for delivery */
+    channels: ("push" | "email" | "wallet")[];
+    /** Notification content templates for different delivery methods */
+    template: NotificationTemplate;
+}
+/**
+ * Response from sending notifications
+ */
+export interface SendNotificationResponse {
+    /** Whether the request was accepted */
+    ok: boolean;
+    /** Unique ID for this notification */
+    notificationId: string;
+    /** Basic counts for contacts and attempts */
+    counts: {
+        contacts: number;
+        attempts: number;
+    };
+    /** Detailed status for the notification */
+    status: {
+        notification: {
+            /** The notification ID (repeated for convenience) */
+            notificationId: string;
+            /** Current processing state */
+            state: 'queued' | 'sent' | 'failed' | 'confirmed' | string;
+            /** Targets this notification refers to */
+            subjectTargets: NotificationSubjectTarget[];
+            /** Severity of this notification */
+            severity: 'low' | 'normal' | 'important' | 'critical' | string;
+            /** Optional channel overrides used when sending */
+            channelsOverride: Record<string, any>;
+            /** The effective template used */
+            template: NotificationTemplate;
+        };
+        /** Totals across all contacts */
+        totals: {
+            queued: number;
+            sent: number;
+            failed: number;
+            confirmed: number;
+        };
+    };
+}

package/dist/types/comms.js

@@ -0,0 +1,3 @@
+// src/types/comms.ts
+// Communication and notification types for the Smartlinks API
+export {};

package/dist/types/index.d.ts

@@ -8,3 +8,4 @@ export * from "./batch";
 export * from "./variant";
 export * from "./claimSet";
 export * from "./auth";
+export * from "./comms";

package/dist/types/index.js

@@ -10,3 +10,4 @@ export * from "./batch";
 export * from "./variant";
 export * from "./claimSet";
 export * from "./auth";
+export * from "./comms";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.0.40",
+  "version": "1.0.42",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",