@proveanything/smartlinks 2.0.66 → 2.0.68

package/docs/connectors.md

@@ -66,7 +66,7 @@ deterministically. A connector's `shape` and `serialize` must be deterministic t
   "aiGuide": "connector-ai-guide.md"
 },
 "functions": {
-  "files": { "js": { "umd": "dist/functions.umd.js" } },
+  "files": { "js": { "umd": "functions.umd.js" } },
   "definitions": [
     { "name": "testConnection", "trigger": { "type": "http", "method": "POST" },
       "visibility": "admin", "authority": "collection",

package/docs/server-functions.md

@@ -33,7 +33,7 @@ in a bundle alongside your widgets/containers:
 ```jsonc
 {
   "functions": {
-    "files": { "js": { "umd": "dist/functions.umd.js" } },
+    "files": { "js": { "umd": "functions.umd.js" } },
     "definitions": [
       {
         "name": "submitCompetitionEntry",
@@ -98,9 +98,12 @@ export default defineConfig({
 }
 ```
 
-That emits `dist/functions.umd.js` (matching `functions.files.js.umd`), whose named exports the
-platform pairs with your manifest `definitions`. Then **deploy** it — for dev,
-`smartlinks-publish` uploads `dist/` and registers in one step (see
+That emits `dist/functions.umd.js`, whose named exports the platform pairs with your manifest
+`definitions`. In the manifest, `functions.files.js.umd` is **`functions.umd.js`** — relative to the
+published build (the contents of `dist/`), like the widget and container files; not
+`dist/functions.umd.js`. Publishing refuses a release whose functions bundle isn't there.
+
+Then **deploy** it — for dev, `smartlinks-publish` uploads `dist/` and registers in one step (see
 [Deploying & registering](deploying-apps.md)).
 
 ---
@@ -169,6 +172,7 @@ Declare the minimum you need.
 | `network:<host>` | `ctx.fetch` to that host only (repeat for several). Prefer this over blanket `network`. |
 | `network:*.<domain>` | `ctx.fetch` to any subdomain of `<domain>` (not `<domain>` itself), for a customer's own endpoint at a provider, e.g. `network:*.servicebus.windows.net`. `<domain>` needs at least two labels (`*.com` is not honoured). |
 | `secrets:<name>` | `ctx.secrets.get('<name>')` for that one secret (see [Secrets](#secrets--api-keys-per-collection)). |
+| `tools:<name>` / `tools:<family>.*` | `ctx.sl.tools.run('<name>', args)` for a platform tool, e.g. `tools:pdf.create`, or `tools:pdf.*` for every PDF tool (see [Platform tools](#platform-tools--pdfs-labels-barcodes)). |
 
 If you don't declare `network`, `ctx.fetch` is absent. Reading a secret you didn't declare with
 `secrets:<name>` throws.
@@ -606,6 +610,58 @@ await ctx.sl.interactions.record({
 
 ---
 
+## Platform tools — PDFs, labels, barcodes
+
+`ctx.sl.tools.run(name, args)` runs one of the platform's deterministic tools from your function: no
+model, no agent loop. Declare each tool as a capability: `tools:pdf.create`, or `tools:pdf.*` for the
+whole family. Open to functions: `pdf.create`, `pdf.merge`, `pdf.fill`, `pdf.inspect`, `pdf.render`,
+`pdf.decodeBarcodes`, `pdf.inspectGraphics`, `pdf.preflight`, `pdf.printReady`, `pdf.edit`,
+`image.transform` (arguments as in [ai.md](ai.md)).
+
+- **Identity:** the call runs as the function's collection, whatever the caller. An anonymous caller
+  holding only your own key gets the same result; the work is attributed and billed to the collection.
+- **Rate:** per collection (10 calls a second by default); bursts wait rather than fail.
+- **Failure:** throws an `Error` with `code` (`bad_args`, `too_large`, `too_many_pages`,
+  `resource_timeout`, `timeout`, `busy`, `TOOL_NOT_AVAILABLE`, or a capability denial).
+
+**Labels with `pdf.create`.** Exact page sizes, many pages in one render, and bytes straight back:
+
+```ts
+// capabilities: ["tools:pdf.create", "tools:pdf.decodeBarcodes"]
+export async function printLabel(ctx, event) {
+  const { gtin, lot, expiry, qty = 1 } = event.body
+  const barcode = bwipjs.toSVG({ bcid: 'gs1-128', text: `(01)${gtin}(10)${lot}(17)${expiry}` }) // inline SVG
+  const pdf = await ctx.sl.tools.run('pdf.create', {
+    width: 100, height: 50, unit: 'mm',                      // exact; output is 1:1
+    head: '<style>.l{position:absolute;font:3mm Arial}</style>',
+    pages: Array.from({ length: qty }, () => `<div class="l" style="left:4mm;top:3mm">Lot ${lot}</div>
+      <div style="position:absolute;left:4mm;top:10mm;width:92mm">${barcode}</div>`),
+    return: 'base64',                                        // or 'signedUrl' + expiresIn
+  })
+  return { pdf: pdf.base64, pages: pdf.pageCount }
+}
+```
+
+- **Page size:** `width` + `height` (+ `unit`: mm, cm, in, pt, px) is exact to the point. Otherwise
+  `format` ("A4", "Letter"), or the document's own CSS `@page { size }` when neither is given.
+- **Pages:** `pages: [html, …]` lays one fragment per page; with an exact size and no margin each page
+  box is that size (overflow hidden), so a long value can't push onto the next label. Up to 2000 pages
+  and 10 MB of HTML per render.
+- **Output:** 1:1 at scale 1 with backgrounds; text stays text and SVG stays vector (render barcodes as
+  inline SVG, e.g. bwip-js `toSVG`, never as a canvas bitmap). Colour is RGB; for CMYK pass the result
+  through `pdf.printReady`.
+- **What loads:** JavaScript does not run. Images, fonts and stylesheets load only from SmartLinks hosts
+  (our CDN), Google Fonts or inline `data:` URIs; anything else is skipped and listed in `warnings`.
+  Embed brand fonts as `data:` URIs in `@font-face`, or host them on the SmartLinks CDN.
+- **Delivery:** `return: 'base64'` (nothing stored), `'signedUrl'` (private link that expires after
+  `expiresIn` seconds, default 900, max 7 days — use this for anything with lot, expiry or serial
+  data), or `'url'` (public and permanent — artwork and documents meant to be shared).
+- **Cache:** the same inputs return the earlier render without rendering again (`cached: true`).
+- **Verify:** `pdf.decodeBarcodes` on a `signedUrl` reads the codes back deterministically, so you can
+  confirm the digits before answering.
+
+---
+
 ## Worked example — a public competition entry
 
 ```ts

package/openapi.yaml

@@ -2077,6 +2077,45 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/collection/{collectionId}/authKit/{authKitId}/identity:
+    post:
+      tags:
+        - authKit
+      summary: "Give this AuthKit its **own logins** (admin): its members become accounts of this site only — the same email can be a separate account, with its own password, on another site — rather than SmartLinks accounts shared across sites."
+      operationId: authKit_setIdentity
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: authKitId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AuthKitSetIdentityResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
   /admin/collection/{collectionId}/batch:
     get:
       tags:
@@ -3715,7 +3754,7 @@ paths:
     get:
       tags:
         - collection
-      summary: "Get the managed-certificate status for a collection's custom domain (admin only)."
+      summary: "Get the certificate status of the collection's own domain (admin only)."
       operationId: collection_getDomainStatus
       security:
         - bearerAuth: []
@@ -3740,7 +3779,7 @@ paths:
     post:
       tags:
         - collection
-      summary: Register a custom domain for a collection and provision its managed certificate (admin only).
+      summary: "Connect one of the collection's own domains and start its certificate (admin only)."
       operationId: collection_registerDomain
       security:
         - bearerAuth: []
@@ -8339,7 +8378,7 @@ paths:
     get:
       tags:
         - tags
-      summary: Reverse lookup — find all tags linked to a given object (admin).
+      summary: Reverse lookup — find all tags linked to a given object (admin).
       operationId: tags_byRef
       security:
         - bearerAuth: []
@@ -9207,7 +9246,7 @@ paths:
     post:
       tags:
         - authKit
-      summary: authKit.linkedInLogin
+      summary: Sign in with LinkedIn (OpenID Connect) via a server-side authorization code (public).
       operationId: authKit_linkedInLogin
       security: []
       parameters:
@@ -14108,7 +14147,7 @@ paths:
     get:
       tags:
         - tags
-      summary: "Global tag resolve — returns `{ tagId, collectionId }` only."
+      summary: "Global tag resolve — returns `{ tagId, collectionId }` only."
       operationId: tags_resolveTag
       security: []
       parameters:
@@ -17499,14 +17538,74 @@ components:
       properties:
         html:
           type: string
+        pages:
+          type: array
+          items:
+            type: string
+        head:
+          type: string
+        width:
+          type: number
+        height:
+          type: number
+        unit:
+          type: string
+          enum:
+            - mm
+            - cm
+            - in
+            - pt
+            - px
         format:
           type: string
         landscape:
           type: boolean
         margin:
           type: string
+        return:
+          type: string
+          enum:
+            - url
+            - signedUrl
+            - base64
+        expiresIn:
+          type: number
+        filename:
+          type: string
+        cache:
+          type: boolean
+    PdfCreateResult:
+      type: object
+      properties:
+        url:
+          type: string
+        hostedUrl:
+          type: string
+        base64:
+          type: string
+        expiresAt:
+          type: string
+        contentType:
+          type: string
+          enum:
+            - application/pdf
+        size:
+          type: number
+        pageCount:
+          type: number
+        cached:
+          type: boolean
+        renderer:
+          type: string
+        warnings:
+          type: array
+          items:
+            type: string
       required:
-        - html
+        - contentType
+        - size
+        - pageCount
+        - cached
     PdfFillArgs:
       type: object
       properties:
@@ -19657,6 +19756,9 @@ components:
         interactions:
           type: object
           additionalProperties: true
+        tools:
+          type: object
+          additionalProperties: true
         products: {}
         attestations: {}
         appData:
@@ -19667,6 +19769,7 @@ components:
         - tags
         - contacts
         - interactions
+        - tools
         - products
         - attestations
         - appData
@@ -23263,8 +23366,38 @@ components:
           type: string
         security:
           $ref: "#/components/schemas/AuthKitSecurityConfig"
+        collectionIds:
+          type: array
+          items:
+            type: string
+        identity:
+          $ref: "#/components/schemas/AuthKitIdentity"
       required:
         - id
+    AuthKitIdentity:
+      type: object
+      properties:
+        mode:
+          type: string
+          enum:
+            - shared
+            - own
+        tenantId:
+          type: string
+        createdAt:
+          type: string
+      required:
+        - mode
+    AuthKitSetIdentityResponse:
+      type: object
+      properties:
+        identity:
+          $ref: "#/components/schemas/AuthKitIdentity"
+        message:
+          type: string
+      required:
+        - identity
+        - message
     AuthKitSecurityConfig:
       type: object
       properties:

package/package.json

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