@proveanything/smartlinks 1.16.7 → 1.17.4

package/dist/types/index.d.ts

@@ -38,5 +38,7 @@ export * from "./appManifest";
 export * from "./appObjects";
 export * from "./loyalty";
 export * from "./translations";
+export * from "./integrations";
+export * from "./research";
 export * from "./config";
 export * from "./widgets";

package/dist/types/index.js

@@ -40,5 +40,7 @@ export * from "./appManifest";
 export * from "./appObjects";
 export * from "./loyalty";
 export * from "./translations";
+export * from "./integrations";
+export * from "./research";
 export * from "./config";
 export * from "./widgets";

package/dist/types/integrations.d.ts

@@ -0,0 +1,136 @@
+export type FlowDirection = 'inbound' | 'outbound';
+export type FlowStatus = 'draft' | 'active' | 'paused' | 'error';
+export type RunStatus = 'success' | 'partial' | 'error';
+/** How one source field maps to one target field during transform. */
+export type TransformType = 'direct' | 'static' | 'template' | 'jsonata' | 'ai';
+export interface FieldMapping {
+    /** Dot-path in the produced target object (required). */
+    targetPath: string;
+    /** Dot-path in the source record. Used by `direct`. */
+    sourcePath?: string;
+    transformType: TransformType;
+    /** Constant (`static`) or Liquid template (`template`), etc. */
+    transformExpression?: string;
+}
+export type FlowAuthMethod = 'api_key' | 'bearer' | 'basic' | 'webhook' | 'oauth2' | 'none';
+export interface FlowConnectionAuth {
+    method: FlowAuthMethod;
+    /** Header name for `api_key` (defaults server-side to X-API-Key). */
+    headerName?: string;
+    /** Opaque reference into the secret store; resolved server-side at execution. */
+    credentialRef?: string;
+}
+export interface FlowConnection {
+    baseUrl?: string;
+    /** Outbound: path appended to baseUrl for sends. */
+    sendEndpoint?: string;
+    /** Inbound: path appended to baseUrl for fetches. */
+    fetchEndpoint?: string;
+    defaultHeaders?: Record<string, string>;
+    auth?: FlowConnectionAuth;
+}
+export interface IntegrationFlowConfig {
+    connection?: FlowConnection;
+    fieldMappings?: FieldMapping[];
+    [key: string]: any;
+}
+export interface IntegrationFlow {
+    id: string;
+    orgId: string;
+    collectionId: string;
+    appId: string;
+    direction: FlowDirection;
+    name: string;
+    status: FlowStatus;
+    /** Event types this flow subscribes to, e.g. ['product.updated']. */
+    eventTypes: string[];
+    /** Cron/interval string for scheduled flows, or null. */
+    schedule: string | null;
+    sourceEntity: string | null;
+    targetEntity: string | null;
+    config: IntegrationFlowConfig;
+    createdBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt?: string | null;
+    lastRunAt?: string | null;
+    lastRunStatus?: string | null;
+    lastRunError?: string | null;
+    lastRunCount?: number | null;
+    lastPollAt?: string | null;
+    lastCursor?: string | null;
+    totalSynced?: number | null;
+}
+export interface CreateFlowInput {
+    appId: string;
+    direction: FlowDirection;
+    name: string;
+    status?: FlowStatus;
+    eventTypes?: string[];
+    schedule?: string | null;
+    sourceEntity?: string | null;
+    targetEntity?: string | null;
+    config?: IntegrationFlowConfig;
+}
+export type UpdateFlowInput = Partial<Omit<CreateFlowInput, 'direction'>> & {
+    status?: FlowStatus;
+};
+export interface ListFlowsQuery {
+    direction?: FlowDirection;
+    status?: FlowStatus;
+    appId?: string;
+}
+export interface FlowList {
+    flows: IntegrationFlow[];
+}
+/** Options for a manual flow run. */
+export interface RunFlowInput {
+    /** Run for a single source entity; omit for the flow's scheduled gather. */
+    entityId?: string;
+}
+/** Inline (synchronous) run summary. */
+export interface RunFlowSummary {
+    flowId: string;
+    direction: FlowDirection;
+    records: number;
+    sent: number;
+    failed: number;
+    status: RunStatus;
+}
+/** Response when a run is enqueued (?async=true). */
+export interface RunFlowEnqueued {
+    enqueued: true;
+    flowId: string;
+    entityId: string | null;
+}
+export type RunFlowResult = RunFlowSummary | RunFlowEnqueued;
+/** Metadata for a stored secret. NEVER includes the value or ciphertext. */
+export interface SecretMeta {
+    ref: string;
+    name: string | null;
+    purpose: string;
+    /** Masked hint (e.g. last few chars) — safe to display. */
+    hint: string;
+    keyVersion: number;
+    createdBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+    rotatedAt?: string | null;
+}
+export interface SecretList {
+    secrets: SecretMeta[];
+}
+export interface SetSecretInput {
+    value: string;
+    name?: string;
+    /** Grouping/scoping label, defaults to 'integration' server-side. */
+    purpose?: string;
+}
+/** Result of set/rotate — the ref to store on a flow's connection, plus a hint. */
+export interface SetSecretResult {
+    ref: string;
+    hint: string;
+}
+export interface ListSecretsQuery {
+    purpose?: string;
+}

package/dist/types/integrations.js

@@ -0,0 +1,10 @@
+// src/types/integrations.ts
+//
+// Integration flows + the sealed-secret store that backs their credentials.
+//
+// A flow is one input/output pipeline: an inbound flow fetches from an external
+// system and writes a SmartLinks entity; an outbound flow reads a SmartLinks entity,
+// transforms it, and sends it out. Credentials are never stored on the flow — the
+// connection carries a `credentialRef` into the secret store, resolved server-side
+// only, at execution.
+export {};

package/dist/types/research.d.ts

@@ -0,0 +1,22 @@
+export interface ResearchFetchRequest {
+    /** Absolute URL to fetch (https). */
+    url: string;
+    /** schema.org @type filter for the returned JSON-LD, e.g. "Recipe" or "Product". */
+    type?: string;
+    /** Alias for `type`. */
+    schemaType?: string;
+    /** Bypass the cache and re-fetch. */
+    forceRefresh?: boolean;
+}
+export interface ResearchFetchResult {
+    provider: 'firecrawl' | 'web';
+    status: number | null;
+    markdown?: string | null;
+    html?: string | null;
+    metadata?: Record<string, any> | null;
+    /** schema.org JSON-LD objects (filtered by `type` when provided). */
+    schemas: any[];
+    url: string;
+    cached: boolean;
+    fetchedAt?: string;
+}

package/dist/types/research.js

@@ -0,0 +1,6 @@
+// src/types/research.ts
+//
+// Web research: fetch + extract a page server-side (Firecrawl-primary, puppeteer
+// fallback), returning clean markdown, page metadata, and deterministic schema.org
+// JSON-LD. The structured-data path (e.g. a recipe/product page) needs no AI.
+export {};

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.16.7  |  Generated: 2026-09-09T11:29:21.917Z
+Version: 1.17.4  |  Generated: 2026-09-13T17:10:55.335Z
 
 This is a concise summary of all available API functions and types.
 
@@ -57,6 +57,8 @@ For detailed guides on specific features:
 - **[Analytics](analytics.md)** - Web analytics, link-click tracking, QR/tag scan telemetry, and event reporting
 - **[Analytics Metadata Conventions](analytics-metadata-conventions.md)** - Standard recommended keys and conventions for analytics metadata fields
 - **[Loyalty: Points, Members & Earning Rules](loyalty.md)** - Loyalty schemes, automatic point earning via interaction rules, member balances, transaction history, and manual adjustments
+- **[Integrations](integrations.md)** - Inbound/outbound integration flows + the sealed-secret store; triggers (manual/event/schedule), field mappings, and the Syndigo/Event Hub outbound path
+- **[AI Tools & Skills](ai-tools-and-skills.md)** - The AI capability catalog: skills apps invoke by name (e.g. research.brand), the tools the AI reaches for (web fetch/screenshot/brand assets/image gen), the agent loop, and how apps discover them
 - **[Deep Link Discovery](deep-link-discovery.md)** - Registering and discovering navigable app states for portal menus and AI orchestration
 - **[AI-Native App Manifests](manifests.md)** - How AI workflows discover, configure, and import apps via structured manifests and prose guides
 - **[AI Guide Template](ai-guide-template.md)** - A sample for an app on how to build an AI setup guide
@@ -134,6 +136,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **containers** - Functions for containers operations
 - **facets** - Functions for facets operations
 - **http** - Functions for http operations
+- **integrations** - Functions for integrations operations
 - **jobs** - Functions for jobs operations
 - **journeysAnalytics** - Functions for journeysAnalytics operations
 - **location** - Functions for location operations
@@ -142,6 +145,8 @@ The Smartlinks SDK is organized into the following namespaces:
 - **order** - Functions for order operations
 - **products** - Functions for products operations
 - **realtime** - Functions for realtime operations
+- **research** - Functions for research operations
+- **secrets** - Functions for secrets operations
 - **tags** - Functions for tags operations
 - **template** - Functions for template operations
 - **translations** - Functions for translations operations
@@ -1009,6 +1014,92 @@ interface AISearchPhotosPhoto {
 }
 ```
 
+**AgentRunRequest** (interface)
+```typescript
+interface AgentRunRequest {
+  input?: string
+  prompt?: string
+  instructions?: string
+  model?: string
+  maxSteps?: number
+  allowCapabilities?: string[]
+  only?: string[]
+  exclude?: string[]
+}
+```
+
+**AgentToolResult** (interface)
+```typescript
+interface AgentToolResult {
+  name: string
+  isError: boolean
+  result: any
+}
+```
+
+**AgentRunResult** (interface)
+```typescript
+interface AgentRunResult {
+  finalText: string | null
+  steps: number
+  maxStepsReached: boolean
+  toolResults: AgentToolResult[]
+  availableTools: string[]
+}
+```
+
+**AgentToolDefinition** (interface)
+```typescript
+interface AgentToolDefinition {
+  name: string
+  description: string
+  capabilities: string[]
+  parameters: any
+}
+```
+
+**AgentToolsResponse** (interface)
+```typescript
+interface AgentToolsResponse {
+  tools: AgentToolDefinition[]
+}
+```
+
+**AgentToolsQuery** (interface)
+```typescript
+interface AgentToolsQuery {
+  allowCapabilities?: string
+  only?: string
+  exclude?: string
+}
+```
+
+**SkillDescriptor** (interface)
+```typescript
+interface SkillDescriptor {
+  name: string
+  description: string
+  inputSchema: any
+  outputSchema: any
+  capabilities: string[]
+}
+```
+
+**SkillsListResponse** (interface)
+```typescript
+interface SkillsListResponse {
+  skills: SkillDescriptor[]
+}
+```
+
+**CatalogResponse** (interface)
+```typescript
+interface CatalogResponse {
+  tools: AgentToolDefinition[]
+  skills: SkillDescriptor[]
+}
+```
+
 ### analytics
 
 **AnalyticsLocation** (interface)
@@ -5768,6 +5859,195 @@ interface UploadDoneMessage {
 
 **UploadMessage** = ``
 
+### integrations
+
+**FieldMapping** (interface)
+```typescript
+interface FieldMapping {
+  targetPath: string
+  sourcePath?: string
+  transformType: TransformType
+  transformExpression?: string
+}
+```
+
+**FlowConnectionAuth** (interface)
+```typescript
+interface FlowConnectionAuth {
+  method: FlowAuthMethod
+  headerName?: string
+  credentialRef?: string
+}
+```
+
+**FlowConnection** (interface)
+```typescript
+interface FlowConnection {
+  baseUrl?: string
+  sendEndpoint?: string
+  fetchEndpoint?: string
+  defaultHeaders?: Record<string, string>
+  auth?: FlowConnectionAuth
+}
+```
+
+**IntegrationFlowConfig** (interface)
+```typescript
+interface IntegrationFlowConfig {
+  connection?: FlowConnection
+  fieldMappings?: FieldMapping[]
+  [key: string]: any
+}
+```
+
+**IntegrationFlow** (interface)
+```typescript
+interface IntegrationFlow {
+  id: string
+  orgId: string
+  collectionId: string
+  appId: string
+  direction: FlowDirection
+  name: string
+  status: FlowStatus
+  eventTypes: string[]
+  schedule: string | null
+  sourceEntity: string | null
+  targetEntity: string | null
+  config: IntegrationFlowConfig
+  createdBy: string | null
+  createdAt: string
+  updatedAt: string
+  deletedAt?: string | null
+  lastRunAt?: string | null
+  lastRunStatus?: string | null
+  lastRunError?: string | null
+  lastRunCount?: number | null
+  lastPollAt?: string | null
+  lastCursor?: string | null
+  totalSynced?: number | null
+}
+```
+
+**CreateFlowInput** (interface)
+```typescript
+interface CreateFlowInput {
+  appId: string
+  direction: FlowDirection
+  name: string
+  status?: FlowStatus
+  eventTypes?: string[]
+  schedule?: string | null
+  sourceEntity?: string | null
+  targetEntity?: string | null
+  config?: IntegrationFlowConfig
+}
+```
+
+**ListFlowsQuery** (interface)
+```typescript
+interface ListFlowsQuery {
+  direction?: FlowDirection
+  status?: FlowStatus
+  appId?: string
+}
+```
+
+**FlowList** (interface)
+```typescript
+interface FlowList {
+  flows: IntegrationFlow[]
+}
+```
+
+**RunFlowInput** (interface)
+```typescript
+interface RunFlowInput {
+  entityId?: string
+}
+```
+
+**RunFlowSummary** (interface)
+```typescript
+interface RunFlowSummary {
+  flowId: string
+  direction: FlowDirection
+  records: number
+  sent: number
+  failed: number
+  status: RunStatus
+}
+```
+
+**RunFlowEnqueued** (interface)
+```typescript
+interface RunFlowEnqueued {
+  enqueued: true
+  flowId: string
+  entityId: string | null
+}
+```
+
+**SecretMeta** (interface)
+```typescript
+interface SecretMeta {
+  ref: string
+  name: string | null
+  purpose: string
+  hint: string
+  keyVersion: number
+  createdBy: string | null
+  createdAt: string
+  updatedAt: string
+  rotatedAt?: string | null
+}
+```
+
+**SecretList** (interface)
+```typescript
+interface SecretList {
+  secrets: SecretMeta[]
+}
+```
+
+**SetSecretInput** (interface)
+```typescript
+interface SetSecretInput {
+  value: string
+  name?: string
+  purpose?: string
+}
+```
+
+**SetSecretResult** (interface)
+```typescript
+interface SetSecretResult {
+  ref: string
+  hint: string
+}
+```
+
+**ListSecretsQuery** (interface)
+```typescript
+interface ListSecretsQuery {
+  purpose?: string
+}
+```
+
+**FlowDirection** = `'inbound' | 'outbound'`
+
+**FlowStatus** = `'draft' | 'active' | 'paused' | 'error'`
+
+**RunStatus** = `'success' | 'partial' | 'error'`
+
+**TransformType** = `'direct' | 'static' | 'template' | 'jsonata' | 'ai'`
+
+**FlowAuthMethod** = `'api_key' | 'bearer' | 'basic' | 'webhook' | 'oauth2' | 'none'`
+
+**UpdateFlowInput** = `Partial<Omit<CreateFlowInput, 'direction'>> & {`
+
+**RunFlowResult** = `RunFlowSummary | RunFlowEnqueued`
+
 ### interaction
 
 **AdminInteractionsQueryRequest** (interface)
@@ -7766,6 +8046,33 @@ interface AblyTokenRequest {
 
 **RealtimeChannelPattern** = `string`
 
+### research
+
+**ResearchFetchRequest** (interface)
+```typescript
+interface ResearchFetchRequest {
+  url: string
+  type?: string
+  schemaType?: string
+  forceRefresh?: boolean
+}
+```
+
+**ResearchFetchResult** (interface)
+```typescript
+interface ResearchFetchResult {
+  provider: 'firecrawl' | 'web'
+  status: number | null
+  markdown?: string | null
+  html?: string | null
+  metadata?: Record<string, any> | null
+  schemas: any[]
+  url: string
+  cached: boolean
+  fetchedAt?: string
+}
+```
+
 ### segments
 
 **InteractionFilterValue** (interface)
@@ -8604,6 +8911,14 @@ interface Gs1DigitalLinkParams {
 
 ## API Functions
 
+### agent
+
+**run**(collectionId: string, body: AgentRunRequest) → `Promise<AgentRunResult>`
+Run the server-side AI agent loop once: assembles the tool set, runs the model, executes tool calls, and returns the final text + the tool trace. POST /admin/collection/:collectionId/ai/agent/run
+
+**listTools**(collectionId: string, query: AgentToolsQuery = {}) → `Promise<AgentToolsResponse>`
+List the tools the agent can use (optionally scoped by capability / name). GET /admin/collection/:collectionId/ai/agent/tools
+
 ### analytics.admin
 
 **summary**(collectionId: string,
@@ -9921,6 +10236,34 @@ Perform a PATCH request to any API endpoint.
 **del**(path: string) → `Promise<T>`
 Perform a DELETE request to any API endpoint.
 
+### integrations
+
+**listFlows**(collectionId: string, query: ListFlowsQuery = {}) → `Promise<FlowList>`
+List flows in a collection. GET /integrations/flows
+
+**createFlow**(collectionId: string, input: CreateFlowInput) → `Promise<IntegrationFlow>`
+Create a flow. POST /integrations/flows
+
+**getFlow**(collectionId: string, id: string) → `Promise<IntegrationFlow>`
+Get one flow. GET /integrations/flows/:id
+
+**updateFlow**(collectionId: string, id: string, input: UpdateFlowInput) → `Promise<IntegrationFlow>`
+Update whitelisted fields. PUT /integrations/flows/:id
+
+**deleteFlow**(collectionId: string, id: string) → `Promise<`
+Soft-delete a flow. DELETE /integrations/flows/:id
+
+**runFlow**(collectionId: string,
+    id: string,
+    options: RunFlowInput & { async?: boolean } = {}) → `Promise<RunFlowResult>`
+Run a flow now. POST /integrations/flows/:id/run - inline (default): resolves and returns the run summary. - options.async: enqueue on the worker, returns { enqueued: true }. Pass options.entityId to run for a single source entity.
+
+**isRunSummary**(r: RunFlowResult) → `r is RunFlowSummary`
+Type guard: the run executed inline and returned a summary.
+
+**isRunEnqueued**(r: RunFlowResult) → `r is RunFlowEnqueued`
+Type guard: the run was enqueued (async).
+
 ### interactions
 
 **query**(collectionId: string,
@@ -10613,6 +10956,28 @@ Get an Ably token for public (user-scoped) real-time communication. This endpoin
 **getAdminToken**() → `Promise<AblyTokenRequest>`
 Get an Ably token for admin real-time communication. This endpoint returns an Ably TokenRequest that can be used to initialize an Ably client with admin permissions to receive system notifications and alerts. Admin users get subscribe-only (read-only) access to the interaction:{userId} channel pattern. Requires admin authentication (Bearer token). ```ts const tokenRequest = await realtime.getAdminToken() // Use with Ably const ably = new Ably.Realtime.Promise({ authCallback: async (data, callback) => { callback(null, tokenRequest) } }) // Subscribe to admin interaction channel const userId = 'my-user-id' const channel = ably.channels.get(`interaction:${userId}`) await channel.subscribe((message) => { console.log('Admin notification:', message.data) }) ```
 
+### research
+
+**fetch**(collectionId: string, body: ResearchFetchRequest) → `Promise<ResearchFetchResult>`
+Fetch + extract a web page: clean markdown, page metadata, and any schema.org JSON-LD (filtered by `type` when given). Firecrawl-primary, cached per collection. POST /admin/collection/:collectionId/research/fetch
+
+### secrets
+
+**list**(collectionId: string, query: ListSecretsQuery = {}) → `Promise<SecretList>`
+List secrets as refs + masked hints + metadata (never values). GET /secrets
+
+**set**(collectionId: string, input: SetSecretInput) → `Promise<SetSecretResult>`
+Create a secret. POST /secrets → { ref, hint }. Store the ref on a flow.
+
+**get**(collectionId: string, ref: string) → `Promise<SecretMeta>`
+Metadata for one secret (never the value). GET /secrets/:ref
+
+**rotate**(collectionId: string, ref: string, input: SetSecretInput) → `Promise<SetSecretResult>`
+Rotate/update a secret's value (and optionally name/purpose). PUT /secrets/:ref → { ref, hint }
+
+**remove**(collectionId: string, ref: string) → `Promise<`
+Soft-delete a secret. DELETE /secrets/:ref
+
 ### segments
 
 **create**(collectionId: string,
@@ -10643,6 +11008,14 @@ Get an Ably token for admin real-time communication. This endpoint returns an Ab
 **stats**(collectionId: string) → `Promise<SessionStatistics>`
 Get session statistics
 
+### skills
+
+**list**(collectionId: string) → `Promise<SkillsListResponse>`
+List the skills apps can invoke (name, description, input/output schema).
+
+**run**(collectionId: string, name: string, input: Record<string, any> = {}) → `Promise<T>`
+Invoke a skill by name with structured input — the app-facing verb; no prompt-shaping. POST /admin/collection/:collectionId/ai/skills/:name/run
+
 ### tags
 
 **create**(collectionId: string,