@proveanything/smartlinks 1.0.64 → 1.1.0

package/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.0.64  |  Generated: 2025-12-17T19:18:01.383Z
+Version: 1.1.0  |  Generated: 2025-12-18T21:46:20.895Z
 
 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,174 @@ interface AuthKitConfig {
 
 **BatchUpdateRequest** = `any`
 
+### broadcasts
+
+**BroadcastEvent** (interface)
+```typescript
+interface BroadcastEvent {
+  orgId: string
+  broadcastId: string
+  userId?: string
+  contactId?: string
+  channel?: string
+  timestamp: string
+  [k: string]: any
+}
+```
+
+**BroadcastQueryByUser** (interface)
+```typescript
+interface BroadcastQueryByUser {
+  userId?: string
+  contactId?: string
+  from?: string
+  to?: string
+  limit?: number
+}
+```
+
+**RecipientIdsQuery** (interface)
+```typescript
+interface RecipientIdsQuery {
+  broadcastId: string
+  idField?: IdField
+  from?: string
+  to?: string
+  limit?: number
+}
+```
+
+**RecipientsWithoutActionQuery** (interface)
+```typescript
+interface RecipientsWithoutActionQuery {
+  broadcastId: string
+  actionId?: string
+  appId?: string
+  idField?: IdField
+  from?: string
+  to?: string
+  limit?: number
+}
+```
+
+**RecipientsWithActionQuery** (interface)
+```typescript
+interface RecipientsWithActionQuery {
+  broadcastId: string
+  actionId?: string
+  appId?: string
+  outcome?: string
+  idField?: IdField
+  includeOutcome?: boolean
+  from?: string
+  to?: string
+  limit?: number
+}
+```
+
+**RecipientWithOutcome** (interface)
+```typescript
+interface RecipientWithOutcome {
+  id: string; outcome: string
+}
+```
+
+**AppendBroadcastBody** (interface)
+```typescript
+interface AppendBroadcastBody {
+  broadcastId: string
+  userId?: string
+  contactId?: string
+  channel?: string
+  timestamp?: string
+  [k: string]: any
+}
+```
+
+**AppendBroadcastBulkBody** (interface)
+```typescript
+interface AppendBroadcastBulkBody {
+  params: { broadcastId: string; [k: string]: any }
+  ids: string[]
+  idField?: IdField
+}
+```
+
+**AppendResult** (interface)
+```typescript
+interface AppendResult {
+  success: true
+}
+```
+
+**AppendBulkResult** (interface)
+```typescript
+interface AppendBulkResult {
+  success: true; count: number
+}
+```
+
+**CreateBroadcastBody** (interface)
+```typescript
+interface CreateBroadcastBody {
+  appId: string
+  data?: Record<string, any>
+}
+```
+
+**UpdateBroadcastBody** (interface)
+```typescript
+interface UpdateBroadcastBody {
+  appId?: string
+  data?: Record<string, any>
+}
+```
+
+**ListBroadcastsQuery** (interface)
+```typescript
+interface ListBroadcastsQuery {
+  limit?: number
+  offset?: number
+  appId?: string
+}
+```
+
+**BroadcastRecord** (interface)
+```typescript
+interface BroadcastRecord {
+  id: string
+  collectionId: string
+  appId: string
+  templateId?: string
+  segmentId?: string
+  status?: 'draft' | 'scheduled' | 'sending' | 'sent' | string
+  scheduledAt?: string
+  sentAt?: string
+  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
+}
+```
+
+**RecipientId** = `string`
+
 ### claimSet
 
 **ClaimCodeRef** (interface)
@@ -405,6 +775,10 @@ interface CollectionResponse {
 }
 ```
 
+### common
+
+**IdField** = `'userId' | 'contactId'`
+
 ### comms
 
 **NotificationSubjectTarget** (interface)
@@ -561,6 +935,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 +1115,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 +1313,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 +1631,53 @@ 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
+
+**byUser**(collectionId: string,
+    query: BroadcastQueryByUser = {}) → `Promise<BroadcastEvent[]>`
+POST /admin/collection/:collectionId/broadcasts/by-user Returns broadcast events array, newest first.
+
+**recipientIds**(collectionId: string,
+    query: RecipientIdsQuery) → `Promise<RecipientId[]>`
+POST /admin/collection/:collectionId/broadcasts/recipient-ids Returns recipient IDs for a broadcast.
+
+**recipientsWithoutAction**(collectionId: string,
+    query: RecipientsWithoutActionQuery) → `Promise<RecipientId[]>`
+POST /admin/collection/:collectionId/broadcasts/recipients/without-action Returns IDs who received the broadcast but did not perform an action.
+
+**recipientsWithAction**(collectionId: string,
+    query: RecipientsWithActionQuery) → `Promise<RecipientId[] | RecipientWithOutcome[]>`
+POST /admin/collection/:collectionId/broadcasts/recipients/with-action Returns IDs who received the broadcast and performed an action; optionally includes outcome.
+
+**append**(collectionId: string,
+    body: AppendBroadcastBody) → `Promise<AppendResult>`
+POST /admin/collection/:collectionId/broadcasts/append Appends one broadcast event.
+
+**appendBulk**(collectionId: string,
+    body: AppendBroadcastBulkBody | ({ broadcastId: string; ids: string[]; idField?: 'userId'|'contactId'; [k: string]: any }) → `void`
+POST /admin/collection/:collectionId/broadcasts/append/bulk Appends many broadcast recipients. Accepts preferred body shape with params + ids, and legacy flat shape.
+
+**create**(collectionId: string,
+    body: CreateBroadcastBody) → `Promise<BroadcastRecord>`
+POST /admin/collection/:collectionId/broadcasts/append/bulk Appends many broadcast recipients. Accepts preferred body shape with params + ids, and legacy flat shape.
+
+**list**(collectionId: string,
+    query: ListBroadcastsQuery = {}) → `Promise<BroadcastList>`
+POST /admin/collection/:collectionId/broadcasts/append/bulk Appends many broadcast recipients. Accepts preferred body shape with params + ids, and legacy flat shape.
+
+**get**(collectionId: string,
+    id: string) → `Promise<BroadcastRecord>`
+POST /admin/collection/:collectionId/broadcasts/append/bulk Appends many broadcast recipients. Accepts preferred body shape with params + ids, and legacy flat shape.
+
+**update**(collectionId: string,
+    id: string,
+    body: UpdateBroadcastBody) → `Promise<BroadcastRecord>`
+POST /admin/collection/:collectionId/broadcasts/append/bulk Appends many broadcast recipients. Accepts preferred body shape with params + ids, and legacy flat shape.
+
+**remove**(collectionId: string,
+    id: string) → `Promise<void>`
+POST /admin/collection/:collectionId/broadcasts/append/bulk Appends many broadcast recipients. Accepts preferred body shape with params + ids, and legacy flat shape.
+
 ### claimSet
 
 **getAllForCollection**(collectionId: string) → `Promise<any[]>`
@@ -1123,9 +1727,12 @@ Retrieves all Collections.
 **getShortId**(shortId: string) → `Promise<CollectionResponse>`
 Retrieve a collection by its shortId (public endpoint).
 
-**getSettings**(collectionId: string, settingGroup: string) → `Promise<any>`
+**getSettings**(collectionId: string, settingGroup: string, admin?: boolean) → `Promise<any>`
 Retrieve a specific settings group for a collection (public endpoint).
 
+**updateSettings**(collectionId: string, settingGroup: string, settings: any) → `Promise<any>`
+Update a specific settings group for a collection (admin endpoint).
+
 **create**(data: any) → `Promise<CollectionResponse>`
 Create a new collection (admin only).
 
@@ -1214,6 +1821,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>`
@@ -1313,6 +1938,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,