@proveanything/smartlinks 2.0.60 → 2.0.62

package/openapi.yaml

@@ -4417,6 +4417,65 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/collection/{collectionId}/integrations/health:
+    get:
+      tags:
+        - integrations
+      summary: "Every flow at a glance: paused?, running?, last 24h, backlog."
+      operationId: integrations_getHealth
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/IntegrationHealth"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /admin/collection/{collectionId}/integrations/lineage/product/{productId}:
+    get:
+      tags:
+        - integrations
+      summary: "Where a product's data came from (the provider record, when it was fetched and imported, by which run, with the current mapping or an older one) and where it went (each outbound flow's last delivery)."
+      operationId: integrations_getProductLineage
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: productId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProductLineage"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /admin/collection/{collectionId}/integrations/record-types:
     get:
       tags:
@@ -15474,6 +15533,212 @@ components:
       name: X-API-Key
       description: API key for server-to-server calls
   schemas:
+    AdminCardRefresh:
+      type: object
+      properties:
+        on:
+          type: array
+          items:
+            $ref: "#/components/schemas/AdminCardRefreshOn"
+        maxAge:
+          type: object
+          additionalProperties: true
+    AdminCardDeclaration:
+      type: object
+      properties:
+        id:
+          type: string
+        title:
+          type: string
+        description:
+          type: string
+        kind:
+          type: string
+          enum:
+            - data
+            - component
+        function:
+          type: string
+        component:
+          type: string
+        sizes:
+          type: array
+          items:
+            $ref: "#/components/schemas/AdminCardSize"
+        priority:
+          type: number
+        levels:
+          type: array
+          items:
+            type: string
+            enum:
+              - collection
+        refresh:
+          $ref: "#/components/schemas/AdminCardRefresh"
+      required:
+        - id
+        - title
+    AppManifestAdminCards:
+      type: object
+      properties:
+        cards:
+          type: array
+          items:
+            $ref: "#/components/schemas/AdminCardDeclaration"
+        files:
+          type: object
+          additionalProperties: true
+        js:
+          type: object
+          additionalProperties: true
+        css:
+          type: string
+      required:
+        - cards
+        - js
+    AdminCardAction:
+      type: object
+      properties:
+        label:
+          type: string
+        path:
+          type: string
+        url:
+          type: string
+      required:
+        - label
+    AdminCardPayload:
+      type: object
+      properties:
+        title:
+          type: string
+        value:
+          type: object
+          additionalProperties: true
+        label:
+          type: string
+        unit:
+          type: string
+        trend:
+          type: object
+          additionalProperties: true
+        status:
+          type: object
+          additionalProperties: true
+        progress:
+          type: object
+          additionalProperties: true
+        items:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        todo:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        actions:
+          type: array
+          items:
+            $ref: "#/components/schemas/AdminCardAction"
+        empty:
+          type: object
+          additionalProperties: true
+    AdminCard:
+      type: object
+      properties:
+        key:
+          type: string
+        appId:
+          type: string
+        cardId:
+          type: string
+        title:
+          type: string
+        description:
+          type: string
+        kind:
+          type: string
+          enum:
+            - data
+            - component
+        sizes:
+          type: array
+          items:
+            $ref: "#/components/schemas/AdminCardSize"
+        size:
+          $ref: "#/components/schemas/AdminCardSize"
+        priority:
+          type: number
+        state:
+          $ref: "#/components/schemas/AdminCardState"
+        payload:
+          $ref: "#/components/schemas/AdminCardPayload"
+        computedAt:
+          type: number
+        error:
+          type: string
+        component:
+          type: object
+          additionalProperties: true
+      required:
+        - key
+        - appId
+        - cardId
+        - title
+        - kind
+        - sizes
+        - size
+        - priority
+        - state
+        - payload
+        - computedAt
+    StudioHomeLayout:
+      type: object
+      properties:
+        version:
+          type: object
+          additionalProperties: true
+        cards:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+      required:
+        - version
+        - cards
+    AdminCardsResponse:
+      type: object
+      properties:
+        cards:
+          type: array
+          items:
+            $ref: "#/components/schemas/AdminCard"
+        hidden:
+          type: array
+          items:
+            $ref: "#/components/schemas/AdminCard"
+        layout:
+          $ref: "#/components/schemas/StudioHomeLayout"
+      required:
+        - cards
+        - hidden
+        - layout
+    AdminCardSize:
+      type: string
+      enum:
+        - small
+        - medium
+        - wide
+        - full
+    AdminCardRefreshOn:
+      type: object
+      additionalProperties: true
+    AdminCardState:
+      type: string
+      enum:
+        - fresh
     ContentPart:
       type: object
       properties:
@@ -19648,6 +19913,8 @@ components:
         realtime:
           type: object
           additionalProperties: true
+        adminCards:
+          $ref: "#/components/schemas/AppManifestAdminCards"
         data:
           $ref: "#/components/schemas/AppDataDeclaration"
         headless:
@@ -26345,6 +26612,169 @@ components:
         - id
         - status
         - attempts
+    FlowHealth:
+      type: object
+      properties:
+        flowId:
+          type: string
+        name:
+          type: string
+        direction:
+          $ref: "#/components/schemas/FlowDirection"
+        status:
+          $ref: "#/components/schemas/FlowStatus"
+        paused:
+          type: object
+          additionalProperties: true
+        running:
+          type: object
+          additionalProperties: true
+        lastRun:
+          type: object
+          additionalProperties: true
+        last24h:
+          type: object
+          additionalProperties: true
+        runs:
+          type: number
+        byStatus:
+          type: object
+          additionalProperties:
+            type: number
+        records:
+          type: number
+        delivered:
+          type: number
+        failed:
+          type: number
+        failureRate:
+          type: number
+        avgRunMs:
+          type: number
+        recordsPerSecond:
+          type: number
+        backlog:
+          type: object
+          additionalProperties: true
+        landed:
+          type: number
+        waiting:
+          type: number
+        oldestWaitingSince:
+          type: string
+        retrying:
+          type: number
+        retriesDue:
+          type: number
+        gaveUp:
+          type: number
+      required:
+        - flowId
+        - name
+        - direction
+        - status
+        - paused
+        - running
+        - lastRun
+        - last24h
+        - runs
+        - byStatus
+        - records
+        - delivered
+        - failed
+        - failureRate
+        - avgRunMs
+        - recordsPerSecond
+        - backlog
+        - retrying
+        - retriesDue
+        - gaveUp
+    IntegrationHealth:
+      type: object
+      properties:
+        flows:
+          type: array
+          items:
+            $ref: "#/components/schemas/FlowHealth"
+        summary:
+          type: object
+          additionalProperties: true
+      required:
+        - flows
+        - summary
+    ProductLineage:
+      type: object
+      properties:
+        productId:
+          type: string
+        sources:
+          type: object
+          additionalProperties: true
+        source:
+          type: string
+        externalId:
+          type: string
+        flow:
+          type: object
+          additionalProperties: true
+        fetchedAt:
+          type: string
+        processedAt:
+          type: string
+        processedRunId:
+          type: string
+        status:
+          type: string
+          enum:
+            - sent
+            - failed
+            - dead
+        lastError:
+          type: string
+        currentMapping:
+          type: boolean
+        mapping:
+          type: array
+          items:
+            $ref: "#/components/schemas/FieldMapping"
+        payload: {}
+        deliveries:
+          type: object
+          additionalProperties: true
+        lastSentAt:
+          type: string
+        attempts:
+          type: number
+        nextAttemptAt:
+          type: string
+        lastRunId:
+          type: string
+        recentRuns:
+          type: array
+          items:
+            $ref: "#/components/schemas/FlowRun"
+      required:
+        - productId
+        - sources
+        - source
+        - externalId
+        - flow
+        - fetchedAt
+        - processedAt
+        - processedRunId
+        - status
+        - lastError
+        - currentMapping
+        - mapping
+        - deliveries
+        - flow
+        - status
+        - lastSentAt
+        - attempts
+        - nextAttemptAt
+        - lastError
+        - lastRunId
+        - recentRuns
     FailedRecordList:
       type: object
       properties:

package/package.json

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

package/scripts/doctor.mjs

@@ -338,6 +338,54 @@ if (meta.respectsHostTheme) {
   }
 }
 
+// ---- admin cards: declared right, cached, and backed by an admin function ---------------------
+// docs/admin-cards.md. A data card with no function (or a public one) can't load; a card with no
+// refresh rule falls back to a 6h maxAge, which is rarely what's wanted.
+if (manifest.adminCards) {
+  const cards = Array.isArray(manifest.adminCards.cards) ? manifest.adminCards.cards : [];
+  const fns = new Map(((manifest.functions && manifest.functions.definitions) || []).map((f) => [f && f.name, f]));
+  const SIZES = new Set(['small', 'medium', 'wide', 'full']);
+  const ON = /^(records(:[A-Za-z0-9._-]{1,60})?|products|proofs|assets|apps|collection|settings(:[A-Za-z0-9._-]{1,60})?)$/;
+  const cardProblems = [];
+  const before = warnings.length;
+  const seen = new Set();
+  if (!cards.length) warnings.push('adminCards is declared but has no cards.');
+  for (const c of cards) {
+    const id = c && typeof c.id === 'string' ? c.id : '';
+    const label = `admin card "${id || '?'}"`;
+    if (!/^[A-Za-z0-9_-]{1,40}$/.test(id)) { cardProblems.push(`${label}: id must be 1–40 letters, digits, "-" or "_".`); continue; }
+    if (seen.has(id)) cardProblems.push(`${label}: declared twice.`);
+    seen.add(id);
+    if (!c.title) warnings.push(`${label}: has no title.`);
+    const kind = c.kind || 'data';
+    if (kind !== 'data' && kind !== 'component') cardProblems.push(`${label}: kind must be "data" or "component".`);
+    if (kind === 'data' && !c.function) cardProblems.push(`${label}: a data card needs a "function" (an admin server function returning its payload).`);
+    if (c.function) {
+      const fn = fns.get(c.function);
+      if (!fn) cardProblems.push(`${label}: function "${c.function}" isn't in functions.definitions.`);
+      else if ((fn.trigger && fn.trigger.type) !== 'http') cardProblems.push(`${label}: function "${c.function}" must be an http function.`);
+      else if ((fn.visibility || 'admin') !== 'admin') cardProblems.push(`${label}: function "${c.function}" must have visibility "admin" — card data is for the collection's admins.`);
+    }
+    if (kind === 'component') {
+      if (!c.component) cardProblems.push(`${label}: a component card needs "component" (the export name in the adminCards bundle).`);
+      if (!manifest.adminCards.files || !manifest.adminCards.files.js) cardProblems.push(`${label}: component cards need adminCards.files (the adminCards bundle).`);
+      if (!c.function) warnings.push(`${label}: give the component a "function" too — it then gets cached data as a prop instead of fetching on every dashboard load.`);
+    }
+    for (const s of c.sizes || []) if (!SIZES.has(s)) cardProblems.push(`${label}: unknown size "${s}" (small, medium, wide, full).`);
+    const refresh = c.refresh || {};
+    for (const on of refresh.on || []) if (!ON.test(String(on))) cardProblems.push(`${label}: refresh.on "${on}" isn't a change kind (records, records:<type>, products, proofs, assets, apps, collection, settings, settings:<group>).`);
+    if (!(refresh.on || []).length && refresh.maxAge == null) {
+      warnings.push(`${label}: no refresh rule — it's recomputed every 6h. Add refresh.on (what its data depends on, e.g. "records:question") so it updates when that changes and never otherwise.`);
+    }
+  }
+  for (const msg of cardProblems) problems.push({ surface: 'adminCards', spec: null, msg });
+  if (cardProblems.length) {
+    console.log(`${RED}✗${RESET} admin cards`);
+    for (const msg of cardProblems) console.log(`    ${RED}${msg}${RESET}`);
+  } else if (warnings.length === before) console.log(`${GREEN}✓${RESET} admin cards ${DIM}— ${cards.length} card${cards.length === 1 ? '' : 's'}, each backed and cached${RESET}`);
+  else console.log(`${YELLOW}⚠${RESET} admin cards — see below`);
+}
+
 // ---- package.json scripts point at files that exist ------------------------------------------
 // An upgrade that copies a script LINE but not the script FILE breaks every build at that step
 // (e.g. `postbuild: node scripts/smartlinks-deploy.mjs` with no scripts/smartlinks-deploy.mjs).
@@ -366,8 +414,13 @@ console.log('');
 for (const w of warnings) console.log(`${YELLOW}⚠ ${w}${RESET}`);
 
 if (problems.length) {
-  console.log(`\n${RED}${BOLD}FAIL${RESET} — ${problems.length} problem${problems.length === 1 ? '' : 's'} outside the shared-dependency contract.`);
-  console.log(`${DIM}Externalize only the ${CONTRACT.size} contract specifiers (import { SHARED_DEPENDENCY_SPECIFIERS } from '@proveanything/smartlinks'); bundle everything else.${RESET}`);
+  const contractProblems = problems.filter((p) => p.surface !== 'adminCards').length;
+  const cardCount = problems.length - contractProblems;
+  if (contractProblems) {
+    console.log(`\n${RED}${BOLD}FAIL${RESET} — ${contractProblems} problem${contractProblems === 1 ? '' : 's'} outside the shared-dependency contract.`);
+    console.log(`${DIM}Externalize only the ${CONTRACT.size} contract specifiers (import { SHARED_DEPENDENCY_SPECIFIERS } from '@proveanything/smartlinks'); bundle everything else.${RESET}`);
+  }
+  if (cardCount) console.log(`\n${RED}${BOLD}FAIL${RESET} — ${cardCount} admin card problem${cardCount === 1 ? '' : 's'} (docs/admin-cards.md).`);
   process.exit(1);
 }