@proveanything/smartlinks 1.0.65 → 1.1.1

package/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.0.65  |  Generated: 2025-12-17T23:06:41.578Z
+Version: 1.1.1  |  Generated: 2025-12-18T22:33:00.019Z
 
 This is a concise summary of all available API functions and types.
 
@@ -8,25 +8,44 @@ This is a concise summary of all available API functions and types.
 
 The Smartlinks SDK is organized into the following namespaces:
 
-- **ai** - Functions for ai operations
-- **appConfiguration** - Application configuration and settings management
-- **appRecord** - Functions for appRecord operations
-- **asset** - File upload and asset management for collections, products, and proofs
-- **attestation** - Digital attestations and verification for products
-- **auth** - Authentication, login, and user account management
-- **authKit** - Functions for authKit operations
-- **batch** - Product batch management and tracking
-- **claimSet** - Claim creation, management, and verification
-- **collection** - Collection CRUD operations and management
-- **comms** - Functions for comms operations
-- **contact** - Functions for contact operations
-- **crate** - Container/crate management for organizing products
-- **form** - Dynamic form creation and submission
-- **nfc** - Functions for nfc operations
-- **product** - Product CRUD operations and management within collections
-- **proof** - Product proof retrieval and validation
-- **serialNumber** - Functions for serialNumber operations
-- **variant** - Product variant management and tracking
+— Core Data & Configuration —
+- **collection** - Manage collections, settings, and identifiers for your workspace.
+- **product** - Create and manage products within a collection; metadata, tags, media.
+- **variant** - Manage product variants per product; includes serial number helpers.
+- **asset** - Upload and manage media assets for collections, products, and proofs.
+- **batch** - Group products into batches; manage serial number ranges and lookups.
+- **crate** - Organize products in containers/crates for logistics and grouping.
+- **form** - Build and manage dynamic forms used by apps and workflows.
+- **appRecord** - Store and retrieve application-level records tied to a collection.
+- **appConfiguration** - Read/write app configuration and scoped data (collection/product/proof).
+
+— Identity & Access —
+- **auth** - Admin authentication and account ops: login/logout, tokens, account info.
+- **authKit** - End‑user auth flows (email/password, OAuth, phone); profiles and verification.
+- **contact** - Manage customer contacts; CRUD, lookup, upsert, erase.
+
+— Messaging & Audience —
+- **comms** - Send notifications (push, email, wallet); templating, severity, delivery status.
+- **broadcasts** - Define broadcast campaigns; append recipients/events; analytics and CRUD.
+- **segments** - Define dynamic/static audience segments; estimate and list recipients; schedule calculations.
+
+— Analytics & Events —
+- **actions** - Log and analyze actions/outcomes; aggregates and actor lists; action definition CRUD.
+
+— Automation —
+- **journeys** - Configure automated flows triggered by events or schedules; steps, rules; full CRUD.
+
+— NFC, Proofs & Claims —
+- **nfc** - Claim and validate NFC tags; perform tag lookups.
+- **proof** - Create, update, claim, and list product proofs (digital certificates).
+- **claimSet** - Manage claim sets and tag assignments; queries, reports, and updates.
+
+— AI & Utilities —
+- **ai** - Generate content and images, search photos, chat, upload files, and cache.
+- **serialNumber** - Assign, lookup, and manage serial numbers across scopes.
+
+— Other —
+- **attestation** - Functions for attestation operations
 
 ## HTTP Utilities
 
@@ -87,6 +106,189 @@ Sends a custom proxy message to the parent Smartlinks application when running i
 
 ## Types
 
+### actions
+
+**AdminByUserRequest** (interface)
+```typescript
+interface AdminByUserRequest {
+  userId?: string
+  contactId?: string
+  appId?: string
+  actionId?: string
+  broadcastId?: string
+  outcome?: string | null
+  from?: string
+  to?: string
+  limit?: number
+}
+```
+
+**AdminCountsByOutcomeRequest** (interface)
+```typescript
+interface AdminCountsByOutcomeRequest {
+  appId?: string
+  actionId?: string
+  from?: string
+  to?: string
+  limit?: number
+  dedupeLatest?: boolean
+  idField?: IdField
+}
+```
+
+**AdminActorIdsByActionRequest** (interface)
+```typescript
+interface AdminActorIdsByActionRequest {
+  actionId: string
+  idField?: IdField
+  outcome?: string | null
+  includeOutcome?: boolean
+  from?: string
+  to?: string
+  limit?: number
+}
+```
+
+**PublicCountsByOutcomeRequest** (interface)
+```typescript
+interface PublicCountsByOutcomeRequest {
+  appId: string
+  actionId: string
+  from?: string
+  to?: string
+  limit?: number
+}
+```
+
+**PublicByUserRequest** (interface)
+```typescript
+interface PublicByUserRequest {
+  appId: string
+  actionId: string
+  from?: string
+  to?: string
+  limit?: number
+}
+```
+
+**ActionEventRow** (interface)
+```typescript
+interface ActionEventRow {
+  orgId: string
+  timestamp: string
+  appId?: string
+  actionId?: string
+  broadcastId?: string
+  userId?: string
+  contactId?: string
+  outcome?: string | null
+  [k: string]: unknown
+}
+```
+
+**OutcomeCount** (interface)
+```typescript
+interface OutcomeCount {
+  outcome: string | null; count: number
+}
+```
+
+**ActorWithOutcome** (interface)
+```typescript
+interface ActorWithOutcome {
+  id: string; outcome: string | null
+}
+```
+
+**AppendActionBody** (interface)
+```typescript
+interface AppendActionBody {
+  userId?: string
+  contactId?: string
+  actionId: string
+  appId?: string
+  broadcastId?: string
+  outcome?: string
+  timestamp?: string
+  [k: string]: any
+}
+```
+
+**ActionPermissions** (interface)
+```typescript
+interface ActionPermissions {
+  allowOwnRead?: boolean
+  allowPublicSummary?: boolean
+  allowAuthenticatedSummary?: boolean
+}
+```
+
+**ActionRecord** (interface)
+```typescript
+interface ActionRecord {
+  id: string
+  collectionId: string
+  appId: string
+  permissions?: ActionPermissions
+  data?: {
+  display?: {
+  title?: string
+  description?: string
+  icon?: string
+  color?: string
+  }
+  actionType?: string
+  [key: string]: unknown
+  }
+  createdAt: string
+}
+```
+
+**ActionList** (interface)
+```typescript
+interface ActionList {
+  items: ActionRecord[]
+  limit: number
+  offset: number
+}
+```
+
+**CreateActionBody** (interface)
+```typescript
+interface CreateActionBody {
+  id: string
+  appId: string
+  permissions?: ActionPermissions
+  data?: Record<string, unknown>
+}
+```
+
+**UpdateActionBody** (interface)
+```typescript
+interface UpdateActionBody {
+  appId?: string
+  permissions?: ActionPermissions
+  data?: Record<string, unknown>
+}
+```
+
+**ListActionsQuery** (interface)
+```typescript
+interface ListActionsQuery {
+  appId?: string
+  limit?: number
+  offset?: number
+}
+```
+
+**ActorId** = `string`
+
+**ActionQueryByUser** = `AdminByUserRequest`
+
+**ActionCountsQuery** = `AdminCountsByOutcomeRequest`
+
+**ActorIdsByActionQuery** = `AdminActorIdsByActionRequest`
+
 ### appConfiguration
 
 **AppConfigurationResponse** (interface)
@@ -328,6 +530,51 @@ interface AuthKitConfig {
 
 **BatchUpdateRequest** = `any`
 
+### broadcasts
+
+**ListBroadcastsQuery** (interface)
+```typescript
+interface ListBroadcastsQuery {
+  limit?: number
+  offset?: number
+  appId?: string
+}
+```
+
+**BroadcastRecord** (interface)
+```typescript
+interface BroadcastRecord {
+  id: string
+  collectionId: string
+  appId: string
+  templateId?: string | null
+  segmentId?: string | null
+  status?: string | null
+  scheduledAt?: string | null
+  sentAt?: string | null
+  data?: {
+  display?: {
+  title?: string
+  description?: string
+  icon?: string
+  color?: string
+  }
+  broadcastType?: string
+  [key: string]: unknown
+  }
+  createdAt: string
+}
+```
+
+**BroadcastList** (interface)
+```typescript
+interface BroadcastList {
+  items: BroadcastRecord[]
+  limit: number
+  offset: number
+}
+```
+
 ### claimSet
 
 **ClaimCodeRef** (interface)
@@ -405,6 +652,10 @@ interface CollectionResponse {
 }
 ```
 
+### common
+
+**IdField** = `'userId' | 'contactId'`
+
 ### comms
 
 **NotificationSubjectTarget** (interface)
@@ -491,6 +742,119 @@ interface SendNotificationResponse {
 }
 ```
 
+**CommunicationEvent** (interface)
+```typescript
+interface CommunicationEvent {
+  orgId: string
+  sourceId?: string
+  userId?: string
+  contactId?: string
+  channel?: string
+  timestamp: string
+  eventType?: string
+  outcome?: string | null
+  templateId?: string | null
+  [k: string]: any
+}
+```
+
+**CommsQueryByUser** (interface)
+```typescript
+interface CommsQueryByUser {
+  userId?: string
+  contactId?: string
+  from?: string
+  to?: string
+  limit?: number
+}
+```
+
+**RecipientWithOutcome** (interface)
+```typescript
+interface RecipientWithOutcome {
+  id: string; outcome: string
+}
+```
+
+**CommsRecipientIdsQuery** (interface)
+```typescript
+interface CommsRecipientIdsQuery {
+  sourceId: string
+  idField?: 'userId' | 'contactId'
+  from?: string
+  to?: string
+  limit?: number
+}
+```
+
+**CommsRecipientsWithoutActionQuery** (interface)
+```typescript
+interface CommsRecipientsWithoutActionQuery {
+  sourceId: string
+  actionId?: string
+  appId?: string
+  idField?: 'userId' | 'contactId'
+  from?: string
+  to?: string
+  limit?: number
+}
+```
+
+**CommsRecipientsWithActionQuery** (interface)
+```typescript
+interface CommsRecipientsWithActionQuery {
+  sourceId: string
+  actionId?: string
+  appId?: string
+  outcome?: string
+  idField?: 'userId' | 'contactId'
+  includeOutcome?: boolean
+  from?: string
+  to?: string
+  limit?: number
+}
+```
+
+**LogCommunicationEventBody** (interface)
+```typescript
+interface LogCommunicationEventBody {
+  sourceId: string
+  userId?: string
+  contactId?: string
+  channel?: string
+  eventType?: string
+  outcome?: string
+  templateId?: string
+  timestamp?: string
+  [k: string]: any
+}
+```
+
+**LogBulkCommunicationEventsBody** (interface)
+```typescript
+interface LogBulkCommunicationEventsBody {
+  params: { sourceId: string; [k: string]: any }
+  ids: string[]
+  idField?: 'userId' | 'contactId'
+}
+```
+
+**AppendResult** (interface)
+```typescript
+interface AppendResult {
+  success: true
+}
+```
+
+**AppendBulkResult** (interface)
+```typescript
+interface AppendBulkResult {
+  success: true; count: number
+}
+```
+
+**RecipientId** = `string`
+
 ### contact
 
 **ContactResponse** (interface)
@@ -561,6 +925,78 @@ interface ErrorResponse {
 }
 ```
 
+### journeys
+
+**JourneyRecord** (interface)
+```typescript
+interface JourneyRecord {
+  id: string
+  collectionId: string
+  appId?: string
+  name: string
+  active: boolean
+  journeyType: 'event_triggered' | 'scheduled'
+  data?: {
+  display?: {
+  title?: string
+  description?: string
+  icon?: string
+  color?: string
+  }
+  steps?: Array<{ id: string; type: string; config?: Record<string, unknown> }>
+  triggers?: Array<{ type: string; config?: Record<string, unknown> }>
+  entryRules?: any[]
+  exitRules?: any[]
+  metadata?: Record<string, unknown>
+  [key: string]: unknown
+  }
+  createdAt: string
+  updatedAt: string
+}
+```
+
+**JourneyList** (interface)
+```typescript
+interface JourneyList {
+  items: JourneyRecord[]
+  limit: number
+  offset: number
+}
+```
+
+**ListJourneysQuery** (interface)
+```typescript
+interface ListJourneysQuery {
+  appId?: string
+  active?: boolean
+  journeyType?: 'event_triggered' | 'scheduled'
+  limit?: number
+  offset?: number
+}
+```
+
+**CreateJourneyBody** (interface)
+```typescript
+interface CreateJourneyBody {
+  appId?: string
+  name: string
+  active?: boolean
+  journeyType: 'event_triggered' | 'scheduled'
+  data?: Record<string, unknown>
+}
+```
+
+**UpdateJourneyBody** (interface)
+```typescript
+interface UpdateJourneyBody {
+  appId?: string
+  name?: string
+  active?: boolean
+  journeyType?: 'event_triggered' | 'scheduled'
+  data?: Record<string, unknown>
+}
+```
+
 ### nfc
 
 **NfcTagInfo** (interface)
@@ -669,6 +1105,68 @@ interface ProofResponse {
 }
 ```
 
+### segments
+
+**SegmentRecord** (interface)
+```typescript
+interface SegmentRecord {
+  id: string
+  collectionId: string
+  appId?: string
+  name: string
+  filterType: 'dynamic' | 'static'
+  estimatedCount?: number
+  lastCalculatedAt?: string
+  createdAt: string
+  data?: {
+  filterRules: any[]
+  description?: string
+  staticContactIds?: string[]
+  [key: string]: unknown
+  }
+}
+```
+
+**ListSegmentsQuery** (interface)
+```typescript
+interface ListSegmentsQuery {
+  appId?: string
+  filterType?: 'dynamic' | 'static'
+  limit?: number
+  offset?: number
+}
+```
+
+**SegmentList** (interface)
+```typescript
+interface SegmentList {
+  items: SegmentRecord[]
+  limit: number
+  offset: number
+}
+```
+
+**SegmentCalculateResult** (interface)
+```typescript
+interface SegmentCalculateResult {
+  scheduled: true
+  lastCalculatedAt?: string
+  estimatedCount?: number | null
+  note?: string
+}
+```
+
+**SegmentRecipientsResponse** (interface)
+```typescript
+interface SegmentRecipientsResponse {
+  items: string[]
+  limit: number
+  offset: number
+  total: number
+  note?: string
+}
+```
+
 ### variant
 
 **VariantResponse** = `any`
@@ -805,6 +1303,55 @@ type AccountInfoResponse = {
 
 ## API Functions
 
+### actions
+
+**byUser**(collectionId: string,
+    query: AdminByUserRequest | ActionQueryByUser = {}) → `Promise<ActionEventRow[]>`
+POST /admin/collection/:collectionId/actions/by-user Returns BigQuery action rows, newest first.
+
+**countsByOutcome**(collectionId: string,
+    query: AdminCountsByOutcomeRequest | ActionCountsQuery = {}) → `Promise<OutcomeCount[]>`
+POST /admin/collection/:collectionId/actions/counts-by-outcome Returns array of { outcome, count }.
+
+**actorIdsByAction**(collectionId: string,
+    query: AdminActorIdsByActionRequest | ActorIdsByActionQuery) → `Promise<ActorId[] | ActorWithOutcome[]>`
+POST /admin/collection/:collectionId/actions/actor-ids/by-action Returns list of IDs, optionally with outcome when includeOutcome=true.
+
+**append**(collectionId: string,
+    body: AppendActionBody) → `Promise<`
+POST /admin/collection/:collectionId/actions/append Appends one action event.
+
+**create**(collectionId: string,
+    body: CreateActionBody) → `Promise<ActionRecord>`
+POST /admin/collection/:collectionId/actions/append Appends one action event.
+
+**list**(collectionId: string,
+    query: ListActionsQuery = {}) → `Promise<ActionList>`
+POST /admin/collection/:collectionId/actions/append Appends one action event.
+
+**get**(collectionId: string,
+    id: string) → `Promise<ActionRecord>`
+POST /admin/collection/:collectionId/actions/append Appends one action event.
+
+**update**(collectionId: string,
+    id: string,
+    patchBody: UpdateActionBody) → `Promise<ActionRecord>`
+POST /admin/collection/:collectionId/actions/append Appends one action event.
+
+**remove**(collectionId: string,
+    id: string) → `Promise<void>`
+POST /admin/collection/:collectionId/actions/append Appends one action event.
+
+**publicCountsByOutcome**(collectionId: string,
+    body: PublicCountsByOutcomeRequest,
+    authToken?: string) → `Promise<OutcomeCount[]>`
+POST /admin/collection/:collectionId/actions/append Appends one action event.
+
+**publicMyActions**(collectionId: string,
+    body: PublicByUserRequest,
+    authToken?: string) → `Promise<ActionEventRow[]>`
+POST /admin/collection/:collectionId/actions/append Appends one action event.
+
 ### ai
 
 **generateContent**(collectionId: string,
@@ -1074,6 +1621,24 @@ Get serial numbers for a batch (admin only).
     codeId: string) → `Promise<any>`
 Look up a serial number by code for a batch (admin only).
 
+### broadcasts
+
+**create**(collectionId: string,
+    body: Omit<BroadcastRecord, 'id' | 'collectionId' | 'createdAt'>) → `Promise<BroadcastRecord>`
+
+**list**(collectionId: string,
+    query: ListBroadcastsQuery = {}) → `Promise<BroadcastList>`
+
+**get**(collectionId: string,
+    id: string) → `Promise<BroadcastRecord>`
+
+**update**(collectionId: string,
+    id: string,
+    body: Partial<Omit<BroadcastRecord, 'id' | 'collectionId' | 'createdAt'>>) → `Promise<BroadcastRecord>`
+
+**remove**(collectionId: string,
+    id: string) → `Promise<void>`
+
 ### claimSet
 
 **getAllForCollection**(collectionId: string) → `Promise<any[]>`
@@ -1158,6 +1723,30 @@ Assign a value to a serial number for a collection (admin only).
     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) } ```
 
+**queryByUser**(collectionId: string,
+    body: CommsQueryByUser = {}) → `Promise<CommunicationEvent[]>`
+Analytics: Query communication events by user or contact. POST /admin/collection/:collectionId/comm/query/by-user
+
+**queryRecipientIds**(collectionId: string,
+    body: CommsRecipientIdsQuery) → `Promise<RecipientId[]>`
+Analytics: Recipient IDs for a communication source. POST /admin/collection/:collectionId/comm/query/recipient-ids
+
+**queryRecipientsWithoutAction**(collectionId: string,
+    body: CommsRecipientsWithoutActionQuery) → `Promise<RecipientId[]>`
+Analytics: Recipients who did not perform an action. POST /admin/collection/:collectionId/comm/query/recipients/without-action
+
+**queryRecipientsWithAction**(collectionId: string,
+    body: CommsRecipientsWithActionQuery) → `Promise<RecipientId[] | RecipientWithOutcome[]>`
+Analytics: Recipients who performed an action, optionally with outcome. POST /admin/collection/:collectionId/comm/query/recipients/with-action
+
+**logCommunicationEvent**(collectionId: string,
+    body: LogCommunicationEventBody) → `Promise<AppendResult>`
+Logging: Append a single communication event. POST /admin/collection/:collectionId/comm/log
+
+**logBulkCommunicationEvents**(collectionId: string,
+    body: LogBulkCommunicationEventsBody | ({ sourceId: string; ids: string[]; idField?: 'userId'|'contactId'; [k: string]: any }) → `void`
+Logging: Append many communication events for a list of IDs. POST /admin/collection/:collectionId/comm/log/bulk
+
 ### contact
 
 **create**(collectionId: string, data: ContactCreateRequest) → `Promise<ContactResponse>`
@@ -1217,6 +1806,24 @@ Update a form for a collection (admin only).
 **remove**(collectionId: string, formId: string) → `Promise<void>`
 Delete a form for a collection (admin only).
 
+### journeys
+
+**create**(collectionId: string,
+    body: CreateJourneyBody) → `Promise<JourneyRecord>`
+
+**list**(collectionId: string,
+    query: ListJourneysQuery = {}) → `Promise<JourneyList>`
+
+**get**(collectionId: string,
+    id: string) → `Promise<JourneyRecord>`
+
+**update**(collectionId: string,
+    id: string,
+    body: UpdateJourneyBody) → `Promise<JourneyRecord>`
+
+**remove**(collectionId: string,
+    id: string) → `Promise<void>`
+
 ### nfc
 
 **claimTag**(data: NfcClaimTagRequest) → `Promise<NfcTagInfo>`
@@ -1316,6 +1923,31 @@ Find proofs for a product (admin only). POST /admin/collection/:collectionId/pro
     batchId: string) → `Promise<ProofResponse[]>`
 Get proofs for a batch (admin only). GET /admin/collection/:collectionId/product/:productId/batch/:batchId/proof
 
+### segments
+
+**create**(collectionId: string,
+    body: Omit<SegmentRecord, 'id' | 'collectionId' | 'createdAt'>) → `Promise<SegmentRecord>`
+
+**list**(collectionId: string,
+    query: ListSegmentsQuery = {}) → `Promise<SegmentList>`
+
+**get**(collectionId: string,
+    id: string) → `Promise<SegmentRecord>`
+
+**update**(collectionId: string,
+    id: string,
+    body: Partial<Omit<SegmentRecord, 'id' | 'collectionId' | 'createdAt'>>) → `Promise<SegmentRecord>`
+
+**remove**(collectionId: string,
+    id: string) → `Promise<void>`
+
+**calculate**(collectionId: string,
+    id: string) → `Promise<SegmentCalculateResult>`
+
+**recipients**(collectionId: string,
+    id: string,
+    query: { limit?: number; offset?: number } = {}) → `Promise<SegmentRecipientsResponse>`
+
 ### variant
 
 **get**(collectionId: string,