@proveanything/smartlinks 1.16.7 → 1.17.4

package/dist/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,

package/dist/docs/ai-tools-and-skills.md

@@ -0,0 +1,168 @@
+# AI Tools & Skills
+
+The platform's AI can research the web, extract structured data, screenshot pages, and
+generate images — through a **capability registry**. This page is the catalog: what the
+AI can do, and how an app reaches for it. You should not need to call an API to find
+this out — it's documented here so that when you build an app (or an AI assistant helps
+you), you *know* these capabilities exist and can shape your app to use them.
+
+## Two layers: tools vs skills
+
+- **Skills** are the app-facing verbs — named, composed capabilities with the
+  orchestration and prompt **baked in**. You invoke a skill by name with structured
+  input and get structured output back. **You never write a prompt.** Example:
+  `research.brand`.
+- **Tools** are the atomic building blocks (fetch a page, generate an image). The AI
+  reaches for these *itself* during a skill or agent run — you rarely call them directly.
+
+Rule of thumb: **if a skill exists for what you want, call the skill.** Drop to the
+agent loop (below) only for open-ended tasks with no matching skill.
+
+## Using a skill
+
+```ts
+import { ai } from '@proveanything/smartlinks'
+
+// Research a client's brand from their website — no prompt, just input.
+const { profile, sources } = await ai.skills.run(collectionId, 'research.brand', {
+  url: 'https://acme.com',
+})
+// profile → { name, description, tagline, palette:[{hex}], logoUrl, tone, keyProducts, socials }
+// sources → which signals were available (markdown, branding, schema.org)
+
+// Discover skills at runtime too (this catalog, live):
+const { skills } = await ai.skills.list(collectionId)
+```
+
+## Deterministic extraction (no AI)
+
+For structured pages, skip the LLM entirely — `research.fetch` returns schema.org
+JSON-LD deterministically:
+
+```ts
+const res = await ai./* research */ // see the `research` namespace
+// or the tool directly inside an agent run: web.extractSchema
+```
+(See the **Integrations / research** doc for `research.fetch`, used e.g. by the Recipes
+app to pull a recipe's schema.org data without any AI.)
+
+## Open-ended tasks: the agent loop
+
+When no skill fits, run the agent — it's given the tool catalog and reaches for tools
+as your prompt warrants:
+
+```ts
+const result = await ai.agent.run(collectionId, {
+  prompt: 'Research acme.com and draft a one-paragraph brand summary with 3 hero image ideas.',
+  allowCapabilities: ['web:read', 'ai:image'], // cap blast radius to these capabilities
+})
+// result.finalText + result.toolResults (the trace of tools the AI called)
+
+const { tools } = await ai.agent.listTools(collectionId) // what the AI could reach for
+```
+
+`allowCapabilities` gates which tools a run may use (e.g. omit `ai:image` to forbid
+image generation). Capability tags are listed against each tool below.
+
+## How the AI discovers tools
+
+Within a skill or `ai.agent.run`, the tool definitions (names, descriptions, JSON
+schemas) are passed to the model, so it discovers and calls them automatically. Outside
+a run — e.g. the plain chat endpoints — tools are **not** auto-injected; use a skill or
+the agent loop to give the AI tool access.
+
+---
+
+<!-- The section below is GENERATED from the server registry (single source of truth),
+     also served live at GET /admin/collection/:collectionId/ai/catalog.
+     Regenerate with `node scripts/gen-ai-catalog.js` in prove/server. -->
+
+## Skills
+
+Named, composed capabilities an app invokes **by name** with structured input — no prompt-shaping. Call `SL.ai.skills.run(collectionId, name, input)`.
+
+### `research.brand`
+
+Research a brand or company from its website URL into a structured brand profile (name, description, palette, logo, tone, key products, socials). Gathers page content + schema.org + branding deterministically, then synthesises with AI.
+
+_Capabilities: web:read, ai:text_
+
+**Input**
+- `url` _(required)_ — string: The brand's website URL (https).
+- `instructions` — string: Optional extra guidance for the researcher.
+
+## Tools
+
+Atomic building blocks the AI reaches for **during** an agent/skill run — you rarely call these directly. Enumerable via `SL.ai.agent.listTools(collectionId)`; capability tags cap what a run may use.
+
+### `web.fetchPage`
+
+Fetch a web page by URL and return clean markdown, page metadata, and any structured schema.org/JSON-LD data. Use to research a brand or product website.
+
+_Capabilities: web:read_
+
+**Parameters**
+- `url` _(required)_ — string: Absolute URL to fetch (https).
+- `type` — string: Optional schema.org @type filter for the returned JSON-LD, e.g. "Product" or "Recipe".
+- `forceRefresh` — boolean: Bypass the cache and re-fetch.
+
+### `web.extractSchema`
+
+Fetch a URL and return only its schema.org structured data (JSON-LD) of the given @type, e.g. "Recipe" or "Product". Deterministic — no AI.
+
+_Capabilities: web:read_
+
+**Parameters**
+- `url` _(required)_ — string: Absolute URL to fetch (https).
+- `schemaType` — string: schema.org @type to extract, e.g. "Recipe" or "Product".
+- `forceRefresh` — boolean
+
+### `web.screenshot`
+
+Capture a screenshot of a web page. Returns a stable hosted image URL (screenshotUrl) you can then read with image.describe.
+
+_Capabilities: web:read_
+
+**Parameters**
+- `url` _(required)_ — string: Absolute URL to screenshot (https).
+
+### `image.describe`
+
+Describe an image at a URL, or read text from it (image-to-text / vision). Use on a screenshot or photo to extract what it shows or says.
+
+_Capabilities: ai:vision_
+
+**Parameters**
+- `imageUrl` _(required)_ — string: URL of the image to analyse.
+- `prompt` — string: What to extract or describe (default: describe + transcribe visible text).
+
+### `brand.assets`
+
+Extract a website's brand elements — logo, colours, design — plus page metadata. Use to research a brand's visual identity.
+
+_Capabilities: web:read_
+
+**Parameters**
+- `url` _(required)_ — string: The brand's website URL (https).
+
+### `image.generate`
+
+Generate a new image from a text prompt. Returns the generated image (url or base64).
+
+_Capabilities: ai:image_
+
+**Parameters**
+- `prompt` _(required)_ — string: Description of the image to generate.
+- `size` — string: e.g. "1024x1024".
+- `provider` — `openai` | `gemini`: Image model provider.
+
+### `image.searchStock`
+
+Search stock photography (Unsplash) for real photos matching a query. Returns candidate image URLs.
+
+_Capabilities: web:read_
+
+**Parameters**
+- `query` _(required)_ — string: What to search for.
+- `per_page` — number: How many results (default 10).
+- `orientation` — `landscape` | `portrait` | `squarish`