@proveanything/smartlinks 2.0.29 → 2.0.31

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.29  |  Generated: 2026-09-29T10:33:46.286Z
+Version: 2.0.31  |  Generated: 2026-09-29T19:37:17.528Z
 
 This is a concise summary of all available API functions and types.
 
@@ -4711,6 +4711,27 @@ interface AppConfig {
 }
 ```
 
+**CollectionUser** (interface)
+```typescript
+interface CollectionUser {
+  uid: string
+  access: CollectionAccessLevel | string
+  name?: string
+  email?: string
+}
+```
+
+**InviteUserInput** (interface)
+```typescript
+interface InviteUserInput {
+  email: string
+  name?: string
+  access: CollectionAccessLevel | string
+  loginCollectionId?: string
+  consoleOrigin?: string
+}
+```
+
 **CollectionResponse** = `Collection`
 
 **CollectionCreateRequest** = `Omit<Collection, 'id' | 'shortId'>`
@@ -4719,6 +4740,8 @@ interface AppConfig {
 
 **DomainTarget** = `"smartlinks" | "hub"`
 
+**CollectionAccessLevel** = `'Owner' | 'Admin' | 'Assigner' | 'Reporter' | 'User' | 'None'`
+
 ### common
 
 **IdField** = `'userId' | 'contactId'`
@@ -6539,6 +6562,7 @@ interface FlowList {
 ```typescript
 interface RunFlowInput {
   entityId?: string
+  trigger?: RunTrigger
 }
 ```
 
@@ -6551,6 +6575,128 @@ interface RunFlowSummary {
   sent: number
   failed: number
   status: RunStatus
+  runId?: string
+}
+```
+
+**CapturedRequest** (interface)
+```typescript
+interface CapturedRequest {
+  transport: string
+  method: string
+  url: string
+  headers: Record<string, string>
+  partitionKey?: string
+  body: unknown
+  bodyBytes: number
+  truncated: boolean
+}
+```
+
+**CapturedResponse** (interface)
+```typescript
+interface CapturedResponse {
+  status: number | null
+  ok: boolean | null
+  headers: Record<string, string>
+  body: unknown
+  bodyBytes: number
+  truncated: boolean
+  error: string | null
+}
+```
+
+**FlowRun** (interface)
+```typescript
+interface FlowRun {
+  id: string
+  flowId: string
+  connectionId?: string | null
+  trigger: RunTrigger
+  triggerEvent?: string | null
+  triggerEntityId?: string | null
+  status: FlowRunStatus
+  records: number
+  sent: number
+  failed: number
+  error?: string | null
+  correlationId?: string | null
+  captureLevel: CaptureLevel
+  bodiesPurged: boolean
+  startedAt: string
+  completedAt?: string | null
+  durationMs?: number | null
+}
+```
+
+**FlowRunItem** (interface)
+```typescript
+interface FlowRunItem {
+  id: string
+  runId: string
+  entityType: string
+  entityId?: string | null
+  entityLabel?: string | null
+  status: FlowRunItemStatus
+  skipReason?: string | null
+  request?: CapturedRequest | null
+  response?: CapturedResponse | null
+  attempt: number
+  durationMs?: number | null
+  createdAt: string
+}
+```
+
+**ListRunsQuery** (interface)
+```typescript
+interface ListRunsQuery {
+  status?: FlowRunStatus
+  trigger?: RunTrigger
+  entityId?: string
+  limit?: number
+  cursor?: string
+}
+```
+
+**RunList** (interface)
+```typescript
+interface RunList {
+  runs: FlowRun[]; nextCursor?: string
+}
+```
+
+**ListRunItemsQuery** (interface)
+```typescript
+interface ListRunItemsQuery {
+  status?: FlowRunItemStatus; limit?: number; cursor?: string
+}
+```
+
+**RunItemList** (interface)
+```typescript
+interface RunItemList {
+  items: FlowRunItem[]; nextCursor?: string
+}
+```
+
+**LoggingWindow** (interface)
+```typescript
+interface LoggingWindow {
+  id: string
+  connectionId: string
+  level: CaptureLevel
+  enabledBy?: string | null
+  enabledAt: string
+  expiresAt?: string | null
+  canceledAt?: string | null
+}
+```
+
+**SetLoggingInput** (interface)
+```typescript
+interface SetLoggingInput {
+  ttlMinutes?: number
+  level?: 'full' | 'errors_only'
 }
 ```
 
@@ -6637,6 +6783,14 @@ interface RecordTypesResponse {
 
 **UpdateFlowInput** = `Partial<Omit<CreateFlowInput, 'direction'>> & {`
 
+**RunTrigger** = `'manual' | 'event' | 'schedule' | 'test'`
+
+**FlowRunStatus** = `'running' | 'success' | 'partial' | 'failed' | 'skipped'`
+
+**FlowRunItemStatus** = `'sent' | 'failed' | 'skipped'`
+
+**CaptureLevel** = `'metadata' | 'errors_only' | 'full'`
+
 **RunFlowResult** = `RunFlowSummary | RunFlowEnqueued`
 
 ### interaction
@@ -10433,6 +10587,18 @@ 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).
 
+**getUsers**(collectionId: string) → `Promise<CollectionUser[]>`
+List the users with access to a collection, each with their access level (admin only). Access is stored in the collection's `roles` map (userId → level); this resolves each to name/email. GET /admin/collection/:collectionId/getUsers
+
+**setUserAccess**(collectionId: string,
+    userId: string,
+    access: CollectionAccessLevel | null) → `Promise<void>`
+Grant, change, or remove a user's access level on a collection (admin only). Pass `null` or `'None'` to remove access. The server enforces privilege-escalation rules — you cannot grant an access level above your own, nor change a user whose level is above yours. POST /admin/collection/:collectionId/updateUserAccess
+
+**inviteUser**(collectionId: string,
+    input: InviteUserInput) → `Promise<`
+Invite a user to a collection by email (admin only). Creates or links their account in the login / auth-kit collection (`loginCollectionId`, default `'global'`) and emails them an invite (new account) or an added-to-collection notice (existing account); returns their `uid`. This does NOT grant access on its own — follow with {@link setUserAccess} to set their level (this mirrors the console flow). POST /user/inviteUser
+
 ### comms
 
 **getPushVapidPublicKey**(collectionId: string) → `Promise<import("../types/comms").PushVapidResponse>`
@@ -10815,6 +10981,27 @@ Type guard: the run executed inline and returned a summary.
 **isRunEnqueued**(r: RunFlowResult) → `r is RunFlowEnqueued`
 Type guard: the run was enqueued (async).
 
+**listRuns**(collectionId: string, flowId: string, query: ListRunsQuery = {}) → `Promise<RunList>`
+List a flow's runs, newest first. GET /integrations/flows/:id/runs
+
+**getRun**(collectionId: string, flowId: string, runId: string) → `Promise<FlowRun>`
+Get one run's summary. GET /integrations/flows/:id/runs/:runId
+
+**listRunItems**(collectionId: string, flowId: string, runId: string, query: ListRunItemsQuery = {}) → `Promise<RunItemList>`
+List a run's per-record items. GET /integrations/flows/:id/runs/:runId/items `request`/`response` are populated only for items captured while enhanced logging was active (and before the 24h body purge).
+
+**listEntityRuns**(collectionId: string, entityId: string, query: { limit?: number } = {}) → `Promise<RunList>`
+Every run touching an entity (e.g. a product), across flows. GET /integrations/runs/entity/:entityId
+
+**getLogging**(collectionId: string, connectionId: string) → `Promise<`
+Is enhanced logging active for a connection? GET /integrations/logging/:connectionId
+
+**setLogging**(collectionId: string, connectionId: string, input: SetLoggingInput = {}) → `Promise<`
+Enable enhanced logging. POST /integrations/logging/:connectionId (omit ttlMinutes = until cancelled)
+
+**cancelLogging**(collectionId: string, connectionId: string) → `Promise<`
+Cancel enhanced logging now. DELETE /integrations/logging/:connectionId
+
 ### interactions
 
 **query**(collectionId: string,

package/openapi.yaml

@@ -4334,6 +4334,35 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/collection/{collectionId}/getUsers:
+    get:
+      tags:
+        - collection
+      summary: List the users with access to a collection, each with their access level (admin only).
+      operationId: collection_getUsers
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/CollectionUser"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /admin/collection/{collectionId}/hub:
     post:
       tags:
@@ -4415,6 +4444,38 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/collection/{collectionId}/integrations/runs/entity/{entityId}:
+    get:
+      tags:
+        - integrations
+      summary: Every run touching an entity (e.g.
+      operationId: integrations_listEntityRuns
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: entityId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RunList"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /admin/collection/{collectionId}/interactions:
     get:
       tags:
@@ -8694,6 +8755,38 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/TranslationUpdateRequest"
+  /admin/collection/{collectionId}/updateUserAccess:
+    post:
+      tags:
+        - collection
+      summary: "Grant, change, or remove a user's access level on a collection (admin only)."
+      operationId: collection_setUserAccess
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema: {}
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CollectionAccessLevel"
   /admin/collection/{encodedCollectionId}/comm/send:
     post:
       tags:
@@ -22709,6 +22802,38 @@ components:
             $ref: "#/components/schemas/AppConfig"
       required:
         - apps
+    CollectionUser:
+      type: object
+      properties:
+        uid:
+          type: string
+        access:
+          type: object
+          additionalProperties: true
+        name:
+          type: string
+        email:
+          type: string
+      required:
+        - uid
+        - access
+    InviteUserInput:
+      type: object
+      properties:
+        email:
+          type: string
+        name:
+          type: string
+        access:
+          type: object
+          additionalProperties: true
+        loginCollectionId:
+          type: string
+        consoleOrigin:
+          type: string
+      required:
+        - email
+        - access
     CollectionResponse:
       $ref: "#/components/schemas/Collection"
     CollectionCreateRequest:
@@ -22718,6 +22843,15 @@ components:
     DomainTarget:
       type: object
       additionalProperties: true
+    CollectionAccessLevel:
+      type: string
+      enum:
+        - Owner
+        - Admin
+        - Assigner
+        - Reporter
+        - User
+        - None
     IdField:
       type: string
       enum:
@@ -25148,6 +25282,8 @@ components:
       properties:
         entityId:
           type: string
+        trigger:
+          $ref: "#/components/schemas/RunTrigger"
     RunFlowSummary:
       type: object
       properties:
@@ -25163,6 +25299,8 @@ components:
           type: number
         status:
           $ref: "#/components/schemas/RunStatus"
+        runId:
+          type: string
       required:
         - flowId
         - direction
@@ -25170,6 +25308,209 @@ components:
         - sent
         - failed
         - status
+    CapturedRequest:
+      type: object
+      properties:
+        transport:
+          type: string
+        method:
+          type: string
+        url:
+          type: string
+        headers:
+          type: object
+          additionalProperties:
+            type: string
+        partitionKey:
+          type: string
+        body: {}
+        bodyBytes:
+          type: number
+        truncated:
+          type: boolean
+      required:
+        - transport
+        - method
+        - url
+        - headers
+        - body
+        - bodyBytes
+        - truncated
+    CapturedResponse:
+      type: object
+      properties:
+        status:
+          type: number
+        ok:
+          type: boolean
+        headers:
+          type: object
+          additionalProperties:
+            type: string
+        body: {}
+        bodyBytes:
+          type: number
+        truncated:
+          type: boolean
+        error:
+          type: string
+      required:
+        - status
+        - ok
+        - headers
+        - body
+        - bodyBytes
+        - truncated
+        - error
+    FlowRun:
+      type: object
+      properties:
+        id:
+          type: string
+        flowId:
+          type: string
+        connectionId:
+          type: string
+        trigger:
+          $ref: "#/components/schemas/RunTrigger"
+        triggerEvent:
+          type: string
+        triggerEntityId:
+          type: string
+        status:
+          $ref: "#/components/schemas/FlowRunStatus"
+        records:
+          type: number
+        sent:
+          type: number
+        failed:
+          type: number
+        error:
+          type: string
+        correlationId:
+          type: string
+        captureLevel:
+          $ref: "#/components/schemas/CaptureLevel"
+        bodiesPurged:
+          type: boolean
+        startedAt:
+          type: string
+        completedAt:
+          type: string
+        durationMs:
+          type: number
+      required:
+        - id
+        - flowId
+        - trigger
+        - status
+        - records
+        - sent
+        - failed
+        - captureLevel
+        - bodiesPurged
+        - startedAt
+    FlowRunItem:
+      type: object
+      properties:
+        id:
+          type: string
+        runId:
+          type: string
+        entityType:
+          type: string
+        entityId:
+          type: string
+        entityLabel:
+          type: string
+        status:
+          $ref: "#/components/schemas/FlowRunItemStatus"
+        skipReason:
+          type: string
+        request:
+          $ref: "#/components/schemas/CapturedRequest"
+        response:
+          $ref: "#/components/schemas/CapturedResponse"
+        attempt:
+          type: number
+        durationMs:
+          type: number
+        createdAt:
+          type: string
+      required:
+        - id
+        - runId
+        - entityType
+        - status
+        - attempt
+        - createdAt
+    ListRunsQuery:
+      type: object
+      properties:
+        status:
+          $ref: "#/components/schemas/FlowRunStatus"
+        trigger:
+          $ref: "#/components/schemas/RunTrigger"
+        entityId:
+          type: string
+        limit:
+          type: number
+        cursor:
+          type: string
+    RunList:
+      type: object
+      properties:
+        runs:
+          type: object
+          additionalProperties: true
+      required:
+        - runs
+    ListRunItemsQuery:
+      type: object
+      properties:
+        status:
+          type: object
+          additionalProperties: true
+    RunItemList:
+      type: object
+      properties:
+        items:
+          type: object
+          additionalProperties: true
+      required:
+        - items
+    LoggingWindow:
+      type: object
+      properties:
+        id:
+          type: string
+        connectionId:
+          type: string
+        level:
+          $ref: "#/components/schemas/CaptureLevel"
+        enabledBy:
+          type: string
+        enabledAt:
+          type: string
+        expiresAt:
+          type: string
+        canceledAt:
+          type: string
+      required:
+        - id
+        - connectionId
+        - level
+        - enabledAt
+    SetLoggingInput:
+      type: object
+      properties:
+        ttlMinutes:
+          type: number
+        level:
+          type: string
+          enum:
+            - full
+            - errors_only
     RunFlowEnqueued:
       type: object
       properties:
@@ -25308,6 +25649,33 @@ components:
         - none
     UpdateFlowInput:
       $ref: "#/components/schemas/CreateFlowInput"
+    RunTrigger:
+      type: string
+      enum:
+        - manual
+        - event
+        - schedule
+        - test
+    FlowRunStatus:
+      type: string
+      enum:
+        - running
+        - success
+        - partial
+        - failed
+        - skipped
+    FlowRunItemStatus:
+      type: string
+      enum:
+        - sent
+        - failed
+        - skipped
+    CaptureLevel:
+      type: string
+      enum:
+        - metadata
+        - errors_only
+        - full
     RunFlowResult:
       anyOf:
         - $ref: "#/components/schemas/RunFlowSummary"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.29",
+  "version": "2.0.31",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",