@proveanything/smartlinks 1.17.0 → 1.17.4

package/dist/api/ai.d.ts

@@ -1,4 +1,4 @@
-import type { ContentPart, FunctionCall, ToolCall, ChatMessage, ToolDefinition, ResponseTool, ResponseInputItem, ResponsesRequest, ResponsesResult, ResponsesStreamEvent, ChatCompletionRequest, ChatCompletionChoice, ChatCompletionResponse, ChatCompletionChunk, AIModel, AIModelListParams, AIModelListResponse, DocumentChunk, IndexDocumentRequest, IndexDocumentResponse, ConfigureAssistantRequest, ConfigureAssistantResponse, PublicChatRequest, PublicChatResponse, Session, RateLimitStatus, SessionStatistics, VoiceSessionRequest, VoiceSessionResponse, EphemeralTokenRequest, EphemeralTokenResponse, TranscriptionResponse, TTSRequest, GeneratePodcastRequest, PodcastScript, GeneratePodcastResponse, PodcastStatus, AIGenerateContentRequest, AIGenerateImageRequest, AISearchPhotosRequest, AISearchPhotosPhoto } from "../types/ai";
+import type { ContentPart, FunctionCall, ToolCall, ChatMessage, ToolDefinition, ResponseTool, ResponseInputItem, ResponsesRequest, ResponsesResult, ResponsesStreamEvent, ChatCompletionRequest, ChatCompletionChoice, ChatCompletionResponse, ChatCompletionChunk, AIModel, AIModelListParams, AIModelListResponse, AgentRunRequest, AgentRunResult, AgentToolsQuery, AgentToolsResponse, SkillsListResponse, CatalogResponse, DocumentChunk, IndexDocumentRequest, IndexDocumentResponse, ConfigureAssistantRequest, ConfigureAssistantResponse, PublicChatRequest, PublicChatResponse, Session, RateLimitStatus, SessionStatistics, VoiceSessionRequest, VoiceSessionResponse, EphemeralTokenRequest, EphemeralTokenResponse, TranscriptionResponse, TTSRequest, GeneratePodcastRequest, PodcastScript, GeneratePodcastResponse, PodcastStatus, AIGenerateContentRequest, AIGenerateImageRequest, AISearchPhotosRequest, AISearchPhotosPhoto } from "../types/ai";
 export type { ContentPart, FunctionCall, ToolCall, ChatMessage, ToolDefinition, ResponseTool, ResponseInputItem, ResponsesRequest, ResponsesResult, ResponsesStreamEvent, ChatCompletionRequest, ChatCompletionChoice, ChatCompletionResponse, ChatCompletionChunk, AIModel, AIModelListParams, AIModelListResponse, DocumentChunk, IndexDocumentRequest, IndexDocumentResponse, ConfigureAssistantRequest, ConfigureAssistantResponse, PublicChatRequest, PublicChatResponse, Session, RateLimitStatus, SessionStatistics, VoiceSessionRequest, VoiceSessionResponse, EphemeralTokenRequest, EphemeralTokenResponse, TranscriptionResponse, TTSRequest, GeneratePodcastRequest, PodcastScript, GeneratePodcastResponse, PodcastStatus, AIGenerateContentRequest, AIGenerateImageRequest, AISearchPhotosRequest, AISearchPhotosPhoto, };
 declare namespace aiInternal {
     namespace chat {
@@ -21,6 +21,30 @@ declare namespace aiInternal {
             function create(collectionId: string, request: ChatCompletionRequest): Promise<ChatCompletionResponse | AsyncIterable<ChatCompletionChunk>>;
         }
     }
+    namespace agent {
+        /**
+         * 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
+         */
+        function run(collectionId: string, body: AgentRunRequest): Promise<AgentRunResult>;
+        /**
+         * List the tools the agent can use (optionally scoped by capability / name).
+         * GET /admin/collection/:collectionId/ai/agent/tools
+         */
+        function listTools(collectionId: string, query?: AgentToolsQuery): Promise<AgentToolsResponse>;
+    }
+    namespace skills {
+        /** List the skills apps can invoke (name, description, input/output schema). */
+        function list(collectionId: string): Promise<SkillsListResponse>;
+        /**
+         * Invoke a skill by name with structured input — the app-facing verb; no
+         * prompt-shaping. POST /admin/collection/:collectionId/ai/skills/:name/run
+         */
+        function run<T = any>(collectionId: string, name: string, input?: Record<string, any>): Promise<T>;
+    }
+    /** The full self-describing catalog (tools + skills). GET /ai/catalog */
+    function catalog(collectionId: string): Promise<CatalogResponse>;
     namespace models {
         /**
          * List available AI models
@@ -181,6 +205,15 @@ export declare const ai: {
         listen: typeof aiInternal.voice.listen;
         speak: typeof aiInternal.voice.speak;
     };
+    agent: {
+        run: typeof aiInternal.agent.run;
+        listTools: typeof aiInternal.agent.listTools;
+    };
+    skills: {
+        list: typeof aiInternal.skills.list;
+        run: typeof aiInternal.skills.run;
+    };
+    catalog: typeof aiInternal.catalog;
     generateContent: typeof aiInternal.generateContent;
     generateImage: typeof aiInternal.generateImage;
     searchPhotos: typeof aiInternal.searchPhotos;

package/dist/api/ai.js

@@ -59,6 +59,61 @@ var aiInternal;
         })(completions = chat.completions || (chat.completions = {}));
     })(chat = aiInternal.chat || (aiInternal.chat = {}));
     // ============================================================================
+    // Agent API (server-side tool-registry loop)
+    // ============================================================================
+    let agent;
+    (function (agent) {
+        /**
+         * 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
+         */
+        async function run(collectionId, body) {
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/agent/run`;
+            return post(path, body);
+        }
+        agent.run = run;
+        /**
+         * List the tools the agent can use (optionally scoped by capability / name).
+         * GET /admin/collection/:collectionId/ai/agent/tools
+         */
+        async function listTools(collectionId, query = {}) {
+            const search = new URLSearchParams();
+            for (const [k, v] of Object.entries(query)) {
+                if (v)
+                    search.set(k, String(v));
+            }
+            const qs = search.toString();
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/agent/tools${qs ? `?${qs}` : ''}`;
+            return request(path);
+        }
+        agent.listTools = listTools;
+    })(agent = aiInternal.agent || (aiInternal.agent = {}));
+    // ============================================================================
+    // Skills + Catalog (app-facing discovery)
+    // ============================================================================
+    let skills;
+    (function (skills) {
+        /** List the skills apps can invoke (name, description, input/output schema). */
+        async function list(collectionId) {
+            return request(`/admin/collection/${encodeURIComponent(collectionId)}/ai/skills`);
+        }
+        skills.list = list;
+        /**
+         * Invoke a skill by name with structured input — the app-facing verb; no
+         * prompt-shaping. POST /admin/collection/:collectionId/ai/skills/:name/run
+         */
+        async function run(collectionId, name, input = {}) {
+            return post(`/admin/collection/${encodeURIComponent(collectionId)}/ai/skills/${encodeURIComponent(name)}/run`, input);
+        }
+        skills.run = run;
+    })(skills = aiInternal.skills || (aiInternal.skills = {}));
+    /** The full self-describing catalog (tools + skills). GET /ai/catalog */
+    async function catalog(collectionId) {
+        return request(`/admin/collection/${encodeURIComponent(collectionId)}/ai/catalog`);
+    }
+    aiInternal.catalog = catalog;
+    // ============================================================================
     // Models API
     // ============================================================================
     let models;
@@ -377,6 +432,15 @@ export const ai = {
         listen: aiInternal.voice.listen,
         speak: aiInternal.voice.speak,
     },
+    agent: {
+        run: aiInternal.agent.run,
+        listTools: aiInternal.agent.listTools,
+    },
+    skills: {
+        list: aiInternal.skills.list,
+        run: aiInternal.skills.run,
+    },
+    catalog: aiInternal.catalog,
     generateContent: aiInternal.generateContent,
     generateImage: aiInternal.generateImage,
     searchPhotos: aiInternal.searchPhotos,

package/dist/api/index.d.ts

@@ -39,6 +39,7 @@ export { loyalty } from "./loyalty";
 export { translations } from "./translations";
 export { integrations } from "./integrations";
 export { secrets } from "./secrets";
+export { research } from "./research";
 export { config } from "./config";
 export { http } from "./http";
 export { navigation } from "./navigation";

package/dist/api/index.js

@@ -42,6 +42,7 @@ export { loyalty } from "./loyalty";
 export { translations } from "./translations";
 export { integrations } from "./integrations";
 export { secrets } from "./secrets";
+export { research } from "./research";
 export { config } from "./config";
 export { http } from "./http";
 export { navigation } from "./navigation";

package/dist/api/research.d.ts

@@ -0,0 +1,9 @@
+import type { ResearchFetchRequest, ResearchFetchResult } from "../types/research";
+export declare namespace research {
+    /**
+     * 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
+     */
+    function fetch(collectionId: string, body: ResearchFetchRequest): Promise<ResearchFetchResult>;
+}

package/dist/api/research.js

@@ -0,0 +1,21 @@
+// src/api/research.ts
+//
+// Web research — the direct (deterministic, non-agent) fetch+extract capability.
+// Apps that just want a page's content/structured data call this rather than the AI
+// agent loop (e.g. the Recipes app fetching a recipe's schema.org JSON-LD from a URL).
+//
+// Endpoints: /admin/collection/:collectionId/research
+import { post } from "../http";
+export var research;
+(function (research) {
+    /**
+     * 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
+     */
+    async function fetch(collectionId, body) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/research/fetch`;
+        return post(path, body);
+    }
+    research.fetch = fetch;
+})(research || (research = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.17.0  |  Generated: 2026-09-13T07:38:31.861Z
+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
@@ -143,6 +145,7 @@ 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
@@ -1011,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)
@@ -7957,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)
@@ -8795,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,
@@ -10832,6 +10956,11 @@ 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>`
@@ -10879,6 +11008,14 @@ Soft-delete a secret. DELETE /secrets/:ref
 **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`