@proveanything/smartlinks 1.17.0 → 1.17.4

package/dist/openapi.yaml

@@ -9,6 +9,8 @@ servers:
 tags:
   - name: responses
   - name: completions
+  - name: agent
+  - name: skills
   - name: models
   - name: rag
   - name: sessions
@@ -50,6 +52,7 @@ tags:
   - name: proof
   - name: qr
   - name: realtime
+  - name: research
   - name: segments
   - name: tags
   - name: template
@@ -619,6 +622,108 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/collection/{collectionId}/ai/agent/run:
+    post:
+      tags:
+        - agent
+      summary: "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."
+      operationId: agent_run
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgentRunResult"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AgentRunRequest"
+  /admin/collection/{collectionId}/ai/agent/tools:
+    get:
+      tags:
+        - agent
+      summary: List the tools the agent can use (optionally scoped by capability / name).
+      operationId: agent_listTools
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: allowCapabilities
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: only
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: exclude
+          in: query
+          required: false
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgentToolsResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /admin/collection/{collectionId}/ai/catalog:
+    get:
+      tags:
+        - skills
+      summary: The full self-describing catalog (tools + skills).
+      operationId: skills_catalog
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CatalogResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /admin/collection/{collectionId}/ai/configureAssistant:
     post:
       tags:
@@ -947,6 +1052,33 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/collection/{collectionId}/ai/skills:
+    get:
+      tags:
+        - skills
+      summary: List the skills apps can invoke (name, description, input/output schema).
+      operationId: skills_list
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SkillsListResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /admin/collection/{collectionId}/ai/tts:
     post:
       tags:
@@ -7404,6 +7536,39 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/collection/{collectionId}/research/fetch:
+    post:
+      tags:
+        - research
+      summary: "Fetch + extract a web page: clean markdown, page metadata, and any schema.org JSON-LD (filtered by `type` when given)."
+      operationId: research_fetch
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ResearchFetchResult"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ResearchFetchRequest"
   /admin/collection/{collectionId}/segments:
     get:
       tags:
@@ -15814,6 +15979,143 @@ components:
           type: string
       required:
         - url
+    AgentRunRequest:
+      type: object
+      properties:
+        input:
+          type: string
+        prompt:
+          type: string
+        instructions:
+          type: string
+        model:
+          type: string
+        maxSteps:
+          type: number
+        allowCapabilities:
+          type: array
+          items:
+            type: string
+        only:
+          type: array
+          items:
+            type: string
+        exclude:
+          type: array
+          items:
+            type: string
+    AgentToolResult:
+      type: object
+      properties:
+        name:
+          type: string
+        isError:
+          type: boolean
+        result: {}
+      required:
+        - name
+        - isError
+        - result
+    AgentRunResult:
+      type: object
+      properties:
+        finalText:
+          type: string
+        steps:
+          type: number
+        maxStepsReached:
+          type: boolean
+        toolResults:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgentToolResult"
+        availableTools:
+          type: array
+          items:
+            type: string
+      required:
+        - finalText
+        - steps
+        - maxStepsReached
+        - toolResults
+        - availableTools
+    AgentToolDefinition:
+      type: object
+      properties:
+        name:
+          type: string
+        description:
+          type: string
+        capabilities:
+          type: array
+          items:
+            type: string
+        parameters: {}
+      required:
+        - name
+        - description
+        - capabilities
+        - parameters
+    AgentToolsResponse:
+      type: object
+      properties:
+        tools:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgentToolDefinition"
+      required:
+        - tools
+    AgentToolsQuery:
+      type: object
+      properties:
+        allowCapabilities:
+          type: string
+        only:
+          type: string
+        exclude:
+          type: string
+    SkillDescriptor:
+      type: object
+      properties:
+        name:
+          type: string
+        description:
+          type: string
+        inputSchema: {}
+        outputSchema: {}
+        capabilities:
+          type: array
+          items:
+            type: string
+      required:
+        - name
+        - description
+        - inputSchema
+        - outputSchema
+        - capabilities
+    SkillsListResponse:
+      type: object
+      properties:
+        skills:
+          type: array
+          items:
+            $ref: "#/components/schemas/SkillDescriptor"
+      required:
+        - skills
+    CatalogResponse:
+      type: object
+      properties:
+        tools:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgentToolDefinition"
+        skills:
+          type: array
+          items:
+            $ref: "#/components/schemas/SkillDescriptor"
+      required:
+        - tools
+        - skills
     AnalyticsLocation:
       type: object
       properties:
@@ -26399,6 +26701,51 @@ components:
         - nonce
         - mac
         - clientId
+    ResearchFetchRequest:
+      type: object
+      properties:
+        url:
+          type: string
+        type:
+          type: string
+        schemaType:
+          type: string
+        forceRefresh:
+          type: boolean
+      required:
+        - url
+    ResearchFetchResult:
+      type: object
+      properties:
+        provider:
+          type: string
+          enum:
+            - firecrawl
+            - web
+        status:
+          type: number
+        markdown:
+          type: string
+        html:
+          type: string
+        metadata:
+          type: object
+          additionalProperties: true
+        schemas:
+          type: array
+          items: {}
+        url:
+          type: string
+        cached:
+          type: boolean
+        fetchedAt:
+          type: string
+      required:
+        - provider
+        - status
+        - schemas
+        - url
+        - cached
     InteractionFilterValue:
       type: object
       properties:

package/dist/types/ai.d.ts

@@ -479,3 +479,60 @@ export interface AISearchPhotosPhoto {
     /** Allow extra fields */
     [key: string]: any;
 }
+export interface AgentRunRequest {
+    /** User prompt (either input or prompt). */
+    input?: string;
+    prompt?: string;
+    /** System instructions. */
+    instructions?: string;
+    /** Model id, e.g. 'openai/gpt-5.6-terra'. */
+    model?: string;
+    /** Safety cap on model round-trips. */
+    maxSteps?: number;
+    /** Cap blast radius: only tools whose capabilities are all granted. */
+    allowCapabilities?: string[];
+    /** Restrict to these tool names. */
+    only?: string[];
+    /** Drop these tool names. */
+    exclude?: string[];
+}
+export interface AgentToolResult {
+    name: string;
+    isError: boolean;
+    result: any;
+}
+export interface AgentRunResult {
+    finalText: string | null;
+    steps: number;
+    maxStepsReached: boolean;
+    toolResults: AgentToolResult[];
+    availableTools: string[];
+}
+export interface AgentToolDefinition {
+    name: string;
+    description: string;
+    capabilities: string[];
+    parameters: any;
+}
+export interface AgentToolsResponse {
+    tools: AgentToolDefinition[];
+}
+export interface AgentToolsQuery {
+    allowCapabilities?: string;
+    only?: string;
+    exclude?: string;
+}
+export interface SkillDescriptor {
+    name: string;
+    description: string;
+    inputSchema: any;
+    outputSchema: any;
+    capabilities: string[];
+}
+export interface SkillsListResponse {
+    skills: SkillDescriptor[];
+}
+export interface CatalogResponse {
+    tools: AgentToolDefinition[];
+    skills: SkillDescriptor[];
+}

package/dist/types/index.d.ts

@@ -39,5 +39,6 @@ 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

@@ -41,5 +41,6 @@ export * from "./appObjects";
 export * from "./loyalty";
 export * from "./translations";
 export * from "./integrations";
+export * from "./research";
 export * from "./config";
 export * from "./widgets";

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.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,