@proveanything/smartlinks 1.1.20 → 1.1.22

package/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.1.20  |  Generated: 2026-01-05T11:30:32.718Z
+Version: 1.1.22  |  Generated: 2026-01-07T12:13:29.397Z
 
 This is a concise summary of all available API functions and types.
 
@@ -46,7 +46,9 @@ The Smartlinks SDK is organized into the following namespaces:
 - **serialNumber** - Assign, lookup, and manage serial numbers across scopes.
 
 — Other —
+- **async** - Functions for async operations
 - **attestation** - Functions for attestation operations
+- **jobs** - Functions for jobs operations
 - **journeysAnalytics** - Functions for journeysAnalytics operations
 - **location** - Functions for location operations
 - **template** - Functions for template operations
@@ -1056,6 +1058,71 @@ interface ListInteractionTypesQuery {
 }
 ```
 
+### jobs
+
+**Job** (interface)
+```typescript
+interface Job {
+  id: number
+  task: string
+  payload: any
+  priority: number
+  runAt: string | null
+  createdAt: string
+  attempts: number
+  lastError: string | null
+  lockedAt: string | null
+  key: string | null
+  queueName: string | null
+  status: JobStatus
+}
+```
+
+**ListJobsQuery** (interface)
+```typescript
+interface ListJobsQuery {
+  state?: JobStatus
+  task?: string
+  limit?: number
+  offset?: number
+  from?: string
+  to?: string
+}
+```
+
+**JobsPage** (interface)
+```typescript
+interface JobsPage {
+  items: Job[]
+  limit: number
+  offset: number
+}
+```
+
+**EnqueueAsyncJobRequest** (interface)
+```typescript
+interface EnqueueAsyncJobRequest {
+  task: string
+  payload?: Record<string, any>
+  runAt?: string | Date
+  priority?: number
+  key?: string
+  queueName?: string
+}
+```
+
+**EnqueueAsyncJobResponse** (interface)
+```typescript
+interface EnqueueAsyncJobResponse {
+  id: number
+  task: string
+  runAt?: string
+  key?: string
+}
+```
+
+**JobStatus** = `'queued' | 'running' | 'errored'`
+
 ### journeys
 
 **JourneyRecord** (interface)
@@ -1723,6 +1790,16 @@ Post a chat message to the AI (admin or public)
     onProgress?: (percent: number) → `void`
 Uploads an asset file to a proof, with optional extraData as JSON. Supports progress reporting via onProgress callback (browser only).
 
+### async
+
+**enqueueAsyncJob**(collectionId: string,
+    params: EnqueueAsyncJobRequest) → `Promise<EnqueueAsyncJobResponse>`
+Enqueue a background job for a collection POST /admin/collection/:collectionId/async/jobs (202)
+
+**getAsyncJobStatus**(collectionId: string,
+    jobId: number) → `Promise<Job>`
+Get job status by ID (may return 404 if completed/removed) GET /admin/collection/:collectionId/async/jobs/:jobId
+
 ### attestation
 
 **list**(collectionId: string,
@@ -1937,6 +2014,10 @@ Look up a serial number by code for a batch (admin only).
     id: string,
     body: BroadcastPreviewRequest) → `Promise<BroadcastPreviewResponse>`
 
+**send**(collectionId: string,
+    id: string,
+    body: { pageSize?: number; maxPages?: number; sharedContext?: Record<string, any>; subject?: string } = {}) → `Promise<`
+
 **sendTest**(collectionId: string,
     id: string,
     body: BroadcastSendTestRequest) → `Promise<BroadcastSendTestResponse>`
@@ -2177,6 +2258,24 @@ Appends one interaction event from a public source.
     authToken?: string) → `Promise<InteractionEventRow[]>`
 Appends one interaction event from a public source.
 
+**publicList**(collectionId: string,
+    query: ListInteractionTypesQuery = {}) → `Promise<InteractionTypeList>`
+Appends one interaction event from a public source.
+
+**publicGet**(collectionId: string,
+    id: string) → `Promise<InteractionTypeRecord>`
+Appends one interaction event from a public source.
+
+### jobs
+
+**listJobs**(collectionId: string,
+    query: ListJobsQuery = {}) → `Promise<JobsPage>`
+List visible jobs for a collection GET /admin/collection/:collectionId/jobs
+
+**getJob**(collectionId: string,
+    jobId: number) → `Promise<Job>`
+Get a single job GET /admin/collection/:collectionId/jobs/:jobId
+
 ### journeys
 
 **create**(collectionId: string,

package/README.md

@@ -171,6 +171,60 @@ await broadcasts.appendBulk('collectionId', {
 })
 ```
 
+### Broadcast sending and previews
+
+```ts
+import { broadcasts } from '@proveanything/smartlinks'
+
+// Preview a broadcast (HTML)
+const preview = await broadcasts.preview('collectionId', 'broadcastId', {
+  contactId: 'contact_123',
+  props: { firstName: 'Sam' },
+})
+
+// Send a test email
+await broadcasts.sendTest('collectionId', 'broadcastId', {
+  to: 'test@example.com',
+  subject: 'Test subject',
+  props: { foo: 'bar' },
+})
+
+// Enqueue broadcast sending (background)
+await broadcasts.send('collectionId', 'broadcastId', {
+  pageSize: 100,
+  sharedContext: { campaign: 'summer' },
+})
+
+// Manual page send (for testing/UX)
+const manual = await broadcasts.sendManual('collectionId', 'broadcastId', {
+  limit: 50,
+  dryRun: true,
+})
+```
+
+### Async jobs
+
+```ts
+import { async as slAsync, jobs } from '@proveanything/smartlinks'
+
+// Enqueue an async job
+const queued = await slAsync.enqueueAsyncJob('collectionId', {
+  task: 'email:daily-digest',
+  payload: { segmentId: 'seg_1' },
+  priority: 5,
+  key: 'digest:seg_1',
+})
+
+// Check job status
+const status = await slAsync.getAsyncJobStatus('collectionId', queued.id)
+
+// List recent jobs
+const recent = await jobs.listJobs('collectionId', { state: 'queued', limit: 20 })
+
+// Get a single job
+const job = await jobs.getJob('collectionId', queued.id)
+```
+
 ## Browser and React
 
 The SDK works in modern browsers. Initialize once and call public endpoints without an API key; authenticate to access protected/admin endpoints.

package/dist/api/async.d.ts

@@ -0,0 +1,13 @@
+import type { EnqueueAsyncJobRequest, EnqueueAsyncJobResponse, Job } from "../types/jobs";
+export declare namespace async {
+    /**
+     * Enqueue a background job for a collection
+     * POST /admin/collection/:collectionId/async/jobs (202)
+     */
+    function enqueueAsyncJob(collectionId: string, params: EnqueueAsyncJobRequest): Promise<EnqueueAsyncJobResponse>;
+    /**
+     * Get job status by ID (may return 404 if completed/removed)
+     * GET /admin/collection/:collectionId/async/jobs/:jobId
+     */
+    function getAsyncJobStatus(collectionId: string, jobId: number): Promise<Job>;
+}

package/dist/api/async.js

@@ -0,0 +1,24 @@
+// src/api/async.ts
+import { request, post } from "../http";
+function enc(v) { return encodeURIComponent(v); }
+export var async;
+(function (async) {
+    /**
+     * Enqueue a background job for a collection
+     * POST /admin/collection/:collectionId/async/jobs (202)
+     */
+    async function enqueueAsyncJob(collectionId, params) {
+        const path = `/admin/collection/${enc(collectionId)}/async/jobs`;
+        return post(path, params);
+    }
+    async.enqueueAsyncJob = enqueueAsyncJob;
+    /**
+     * Get job status by ID (may return 404 if completed/removed)
+     * GET /admin/collection/:collectionId/async/jobs/:jobId
+     */
+    async function getAsyncJobStatus(collectionId, jobId) {
+        const path = `/admin/collection/${enc(collectionId)}/async/jobs/${jobId}`;
+        return request(path);
+    }
+    async.getAsyncJobStatus = getAsyncJobStatus;
+})(async || (async = {}));

package/dist/api/broadcasts.d.ts

@@ -11,6 +11,16 @@ export declare namespace broadcasts {
         offset?: number;
     }): Promise<BroadcastRecipientsResponse>;
     function preview(collectionId: string, id: string, body: BroadcastPreviewRequest): Promise<BroadcastPreviewResponse>;
+    function send(collectionId: string, id: string, body?: {
+        pageSize?: number;
+        maxPages?: number;
+        sharedContext?: Record<string, any>;
+        subject?: string;
+    }): Promise<{
+        ok: true;
+        enqueued: true;
+    }>;
+    const sendBroadcast: typeof send;
     function sendTest(collectionId: string, id: string, body: BroadcastSendTestRequest): Promise<BroadcastSendTestResponse>;
     function sendManual(collectionId: string, id: string, body: BroadcastSendManualRequest): Promise<BroadcastSendManualResponse>;
     function append(collectionId: string, body: BroadcastAppendEventBody): Promise<AppendResult>;

package/dist/api/broadcasts.js

@@ -60,6 +60,14 @@ export var broadcasts;
         return post(path, body);
     }
     broadcasts.preview = preview;
+    // Enqueue send for a broadcast (202 Accepted)
+    async function send(collectionId, id, body = {}) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/broadcasts/${encodeURIComponent(id)}/send`;
+        return post(path, body);
+    }
+    broadcasts.send = send;
+    // Alias for clarity with docs naming
+    broadcasts.sendBroadcast = send;
     // Send a single test email
     async function sendTest(collectionId, id, body) {
         const path = `/admin/collection/${encodeURIComponent(collectionId)}/broadcasts/${encodeURIComponent(id)}/send/test`;

package/dist/api/index.d.ts

@@ -17,6 +17,8 @@ export { comms } from "./comms";
 export { nfc } from "./nfc";
 export { contact } from "./contact";
 export { broadcasts } from "./broadcasts";
+export { async } from "./async";
+export { jobs } from "./jobs";
 export { segments } from "./segments";
 export { journeys } from "./journeys";
 export { journeysAnalytics } from "./journeysAnalytics";

package/dist/api/index.js

@@ -19,6 +19,8 @@ export { comms } from "./comms";
 export { nfc } from "./nfc";
 export { contact } from "./contact";
 export { broadcasts } from "./broadcasts";
+export { async } from "./async";
+export { jobs } from "./jobs";
 export { segments } from "./segments";
 export { journeys } from "./journeys";
 export { journeysAnalytics } from "./journeysAnalytics";

package/dist/api/interactions.d.ts

@@ -33,4 +33,6 @@ export declare namespace interactions {
     function remove(collectionId: string, id: string): Promise<void>;
     function publicCountsByOutcome(collectionId: string, body: PublicInteractionsCountsByOutcomeRequest, authToken?: string): Promise<OutcomeCount[]>;
     function publicMyInteractions(collectionId: string, body: PublicInteractionsByUserRequest, authToken?: string): Promise<InteractionEventRow[]>;
+    function publicList(collectionId: string, query?: ListInteractionTypesQuery): Promise<InteractionTypeList>;
+    function publicGet(collectionId: string, id: string): Promise<InteractionTypeRecord>;
 }

package/dist/api/interactions.js

@@ -107,4 +107,17 @@ export var interactions;
         return post(path, body, headers);
     }
     interactions.publicMyInteractions = publicMyInteractions;
+    // Public: list interaction definitions (Postgres)
+    async function publicList(collectionId, query = {}) {
+        const qs = encodeQuery(query);
+        const path = `/public/collection/${encodeURIComponent(collectionId)}/interactions/${qs}`;
+        return request(path);
+    }
+    interactions.publicList = publicList;
+    // Public: get a single interaction definition (Postgres)
+    async function publicGet(collectionId, id) {
+        const path = `/public/collection/${encodeURIComponent(collectionId)}/interactions/${encodeURIComponent(id)}`;
+        return request(path);
+    }
+    interactions.publicGet = publicGet;
 })(interactions || (interactions = {}));

package/dist/api/jobs.d.ts

@@ -0,0 +1,13 @@
+import type { JobsPage, ListJobsQuery, Job } from "../types/jobs";
+export declare namespace jobs {
+    /**
+     * List visible jobs for a collection
+     * GET /admin/collection/:collectionId/jobs
+     */
+    function listJobs(collectionId: string, query?: ListJobsQuery): Promise<JobsPage>;
+    /**
+     * Get a single job
+     * GET /admin/collection/:collectionId/jobs/:jobId
+     */
+    function getJob(collectionId: string, jobId: number): Promise<Job>;
+}

package/dist/api/jobs.js

@@ -0,0 +1,35 @@
+// src/api/jobs.ts
+import { request } from "../http";
+function enc(v) { return encodeURIComponent(v); }
+function encodeQuery(params = {}) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        search.set(key, String(value));
+    }
+    const qs = search.toString();
+    return qs ? `?${qs}` : '';
+}
+export var jobs;
+(function (jobs) {
+    /**
+     * List visible jobs for a collection
+     * GET /admin/collection/:collectionId/jobs
+     */
+    async function listJobs(collectionId, query = {}) {
+        const qs = encodeQuery(query);
+        const path = `/admin/collection/${enc(collectionId)}/jobs${qs}`;
+        return request(path);
+    }
+    jobs.listJobs = listJobs;
+    /**
+     * Get a single job
+     * GET /admin/collection/:collectionId/jobs/:jobId
+     */
+    async function getJob(collectionId, jobId) {
+        const path = `/admin/collection/${enc(collectionId)}/jobs/${jobId}`;
+        return request(path);
+    }
+    jobs.getJob = getJob;
+})(jobs || (jobs = {}));

package/dist/types/index.d.ts

@@ -20,3 +20,4 @@ export * from "./qr";
 export * from "./template";
 export * from "./interaction";
 export * from "./location";
+export * from "./jobs";

package/dist/types/index.js

@@ -22,3 +22,4 @@ export * from "./qr";
 export * from "./template";
 export * from "./interaction";
 export * from "./location";
+export * from "./jobs";

package/dist/types/jobs.d.ts

@@ -0,0 +1,42 @@
+export type JobStatus = 'queued' | 'running' | 'errored';
+export interface Job {
+    id: number;
+    task: string;
+    payload: any;
+    priority: number;
+    runAt: string | null;
+    createdAt: string;
+    attempts: number;
+    lastError: string | null;
+    lockedAt: string | null;
+    key: string | null;
+    queueName: string | null;
+    status: JobStatus;
+}
+export interface ListJobsQuery {
+    state?: JobStatus;
+    task?: string;
+    limit?: number;
+    offset?: number;
+    from?: string;
+    to?: string;
+}
+export interface JobsPage {
+    items: Job[];
+    limit: number;
+    offset: number;
+}
+export interface EnqueueAsyncJobRequest {
+    task: string;
+    payload?: Record<string, any>;
+    runAt?: string | Date;
+    priority?: number;
+    key?: string;
+    queueName?: string;
+}
+export interface EnqueueAsyncJobResponse {
+    id: number;
+    task: string;
+    runAt?: string;
+    key?: string;
+}

package/dist/types/jobs.js

@@ -0,0 +1,2 @@
+// src/types/jobs.ts
+export {};

package/package.json

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