@nivaro/sdk 0.1.16 → 0.1.18

package/README.md

@@ -24,6 +24,14 @@ The `@nivaro/sdk` package is a fully-typed TypeScript client for the Nivaro REST
 pnpm add @nivaro/sdk
 ```
 
+#### MCP server (Claude Code, Claude Desktop, Cursor)
+
+The companion package `@nivaro/mcp` wraps the SDK as a Model Context Protocol server, so an AI coding assistant can read and write an instance directly: collection schemas, record reads and aggregates, rehearsed creates, updates, deletes with an explicit confirm, pipeline state and transitions, and the instance's own ask-your-data assistant. It authenticates with an `nvk_` API key, so role permissions, row-level security and user scopes apply unchanged; a sandbox key is read-only by construction. Install and client config snippets live in the package README (`packages/mcp/README.md`).
+
+```typescript
+claude mcp add nivaro -e NIVARO_URL=https://nivaro.example.com -e NIVARO_TOKEN=nvk_... -- npx -y @nivaro/mcp
+```
+
 #### Create a client
 
 ```typescript
@@ -2446,6 +2454,91 @@ await nivaro.request(createHierarchyConfig({
 
 ---
 
+## SDK — Help Videos
+
+Tutorial recordings: upload, edit, version, publish, choose where they show, require viewing and track progress. Authoring commands need an author (an administrator or a role in the author setting); reading and progress need only visibility.
+
+```typescript
+import {
+  openHelpVideoUpload, finalizeHelpVideoUpload, createHelpVideo,
+  setHelpVideoContexts, publishHelpVideo, helpVideosFor,
+} from '@nivaro/sdk'
+
+// 1. Open an upload, send the bytes, finalize, create the video
+const { data: up } = await nivaro.request(openHelpVideoUpload('video/webm'))
+let part = up.next_part
+for (const chunk of chunks) {
+  // Raw PUT — not a Command, because Commands JSON-encode their bodies.
+  await fetch(`${baseUrl}/api/help-videos/uploads/${up.id}/parts/${part++}`, {
+    method: 'PUT',
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/octet-stream' },
+    body: chunk, // at most 8 MB per part; the response is the upload session
+  })
+}
+await nivaro.request(finalizeHelpVideoUpload(up.id, { duration_ms }))
+const { data: video } = await nivaro.request(createHelpVideo({ upload_id: up.id, title: 'Raise a PO' }))
+
+// 2. Say where it shows, then publish
+await nivaro.request(setHelpVideoContexts(video.id, [{ kind: 'page', key: 'inbox', state_key: null }]))
+await nivaro.request(publishHelpVideo(video.id))
+
+// 3. Show the right videos on a screen
+const { data } = await nivaro.request(helpVideosFor({ collection: 'purchase_orders', item: 42 }))
+```
+
+#### Response notes
+
+- `stream_url`, `captions_url` and `poster_url` are ticketed (`?st=`): hand them to `<video>`, `<track>` and `<img>` as-is. Authors also get `draft_stream_url` and `draft_captions_url`.
+- `published.playable` is `false` when a viewer’s stream would answer 409 (the video is still being prepared); authors always get `true`.
+- `required` is true when the video is required for the caller’s own role. Authors also get `required_role_ids`. `my_progress` is the caller’s own progress (or `null`).
+- `recordHelpVideoProgress` takes `buckets` as a 20-character `0`/`1` string (the 5% sections seen) and answers `{ data: { completed } }`, or no body (204) for a masquerade session.
+- `listHelpVideos` and `helpVideosFor` carry `can_author`, so a screen can offer "Add a video" without a second call.
+
+#### Errors callers must handle
+
+| Status | code | When |
+| --- | --- | --- |
+| 409 | `HELP_VIDEO_PROCESSING` | A viewer requested `stream_url` before a current render exists and the original cannot be shown. Check `published.playable`, retry later. |
+| 409 | `HELP_VIDEO_EDITS_CONFLICT` | `saveHelpVideoDraft` with a stale `base_hash`. The body carries `current_hash`; reload the draft and merge. |
+| 409 | `UPLOAD_CLOSED` | The upload is already finalized or finishing; or, on discard, already used by a video or discarded. |
+| 422 | `UPLOAD_NOT_VIDEO` | A part is not a WebM or MP4 recording. |
+| 422 | `UPLOAD_TOO_LONG` | The recording is longer than 30 minutes (on finalize). |
+| 422 | `HELP_VIDEO_NOT_READY` | `publishHelpVideo` before the checklist is done; the body lists `missing`. |
+| 409 | `HELP_VIDEO_NOTHING_TO_PUBLISH` | `publishHelpVideo` with no draft, or a draft that is exactly the published version (`draft_matches_published`). With `watch_again` on a video someone must watch, it re-asks them instead. |
+| 422 | `HELP_VIDEO_EDITS_INVALID` | `saveHelpVideoDraft` with edits that cannot be kept, such as cuts that leave less than a second. The message says why; the stored draft is unchanged. |
+| 409 | `HELP_VIDEO_NOTHING_TO_RENDER` | `rerenderHelpVideo` for a version that does not exist. |
+| 403 | `HELP_VIDEO_AUTHOR_ONLY` | An authoring command by a non-author. |
+| 404 | `HELP_VIDEO_NOT_FOUND` | Unknown id, or a video the caller may not see. |
+
+| Command | Route | Auth |
+| --- | --- | --- |
+| listHelpVideos(params?) | GET /help-videos | Authenticated |
+| readHelpVideo(id) | GET /help-videos/:id | Authenticated |
+| helpVideosFor(params) | GET /help-videos/for | Authenticated |
+| createHelpVideo(body) | POST /help-videos | Author |
+| updateHelpVideo(id, body) | PATCH /help-videos/:id | Author |
+| setHelpVideoContexts(id, contexts) | PUT /help-videos/:id/contexts | Author |
+| setHelpVideoRequirements(id, role_ids) | PUT /help-videos/:id/requirements | Author |
+| archiveHelpVideo(id, opts?) | DELETE /help-videos/:id | Author (purge: admin, archived videos only) |
+| readHelpVideoDraft(id) | GET /help-videos/:id/draft/edits | Author |
+| saveHelpVideoDraft(id, edits, base_hash?) | PUT /help-videos/:id/draft/edits | Author |
+| publishHelpVideo(id, opts?) | POST /help-videos/:id/publish | Author |
+| rerecordHelpVideo(id, upload_id) | POST /help-videos/:id/rerecord | Author |
+| listHelpVideoVersions(id) | GET /help-videos/:id/versions | Author |
+| restoreHelpVideoVersion(id, versionId) | POST /help-videos/:id/versions/:vid/restore | Author |
+| rerenderHelpVideo(id, opts?) | POST /help-videos/:id/render | Author |
+| recordHelpVideoProgress(id, body) | POST /help-videos/:id/progress | Authenticated |
+| readRequiredHelpVideos() | GET /help-videos/required/mine | Authenticated |
+| readHelpVideoAnalytics(id) | GET /help-videos/:id/analytics | Author |
+| openHelpVideoUpload(mime) | POST /help-videos/uploads | Author |
+| finalizeHelpVideoUpload(id, meta?) | POST /help-videos/uploads/:id/finalize | Author |
+| listMyHelpVideoUploads() | GET /help-videos/uploads/mine | Author |
+| abandonHelpVideoUpload(id) | DELETE /help-videos/uploads/:id | Author |
+| listHelpVideoPages() | GET /help-videos/pages | Authenticated |
+| registerHelpVideoPage(body) | POST /help-videos/pages | Author |
+
+---
+
 ## SDK Coverage: 300+ Typed Commands
 
 The @nivaro/sdk command surface now covers every feature area — roughly 175 typed `Command<T>` factories spanning items, files, workflows, pipelines, flows, comments, webhooks, rules, custom queries, trees and hierarchies, submission forms, field watches, notification subscriptions, imports, SLA, alerts, AI endpoints (generate, summarize, validate, check-duplicates), translations, drafts, scheduled changes, record templates, saved views, API keys, widget feeds, sync jobs, ERP submissions, PDF templates, pages, queues (worklists, items, claims, saved views, trends, workload), roles & policies (RBAC/RLS), user management + out-of-office delegation, file management (list/meta/presign/transform URLs), dashboard widgets, extension item/bulk actions, throughput reporting, and more. If a REST route exists, there is a typed command for it.

package/bin/lib/ext-scaffold.mjs

@@ -0,0 +1,220 @@
+/**
+ * Extension scaffolder (#1302) — `nivaro ext init <id> [--dir api/extensions]`.
+ *
+ * Writes `<dir>/<id>/` with an index.ts written against @nivaro/extension-kit
+ * (one setting, one hook, one described cron, one route behind requireAuth),
+ * a passing test on the kit's createTestContext, and a README naming the
+ * context members the starter uses. Refuses an existing directory and an id
+ * that is not kebab-case.
+ *
+ * Plain ESM so the CLI imports it directly and `node --test` covers it.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve } from 'node:path'
+
+/** kebab-case: lowercase words joined by single hyphens, 2–64 characters. */
+const ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/
+
+/** Null when the id is usable, otherwise the reason it is not. */
+export function validateExtensionId(id) {
+  if (typeof id !== 'string' || id.length === 0) return 'An extension id is required'
+  if (id.length < 2 || id.length > 64) return 'The id must be 2–64 characters'
+  if (!ID.test(id))
+    return `"${id}" is not kebab-case — use lowercase letters, digits and single hyphens (my-extension)`
+  return null
+}
+
+/** The directory the extension goes in when --dir is not given. */
+export function defaultExtensionsDir(cwd = process.cwd()) {
+  if (existsSync(join(cwd, 'api', 'extensions'))) return join(cwd, 'api', 'extensions')
+  if (existsSync(join(cwd, 'extensions', 'tsconfig.json'))) return join(cwd, 'extensions')
+  return join(cwd, 'api', 'extensions')
+}
+
+function camel(id) {
+  return id.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase())
+}
+
+/** The files, by name, for an extension called `id`. */
+export function scaffoldFiles(id) {
+  // The id is written into source text and a path: only a validated one.
+  const bad = validateExtensionId(id)
+  if (bad) throw new Error(bad)
+  const label = id
+    .split('-')
+    .map((w) => w[0].toUpperCase() + w.slice(1))
+    .join(' ')
+  const counter = `${camel(id)}Creates`
+
+  const index = `import { defineExtension } from '@nivaro/extension-kit'
+
+/**
+ * ${label} — scaffolded by \`nivaro ext init ${id}\`.
+ *
+ * One of each thing an extension usually starts with: a setting an admin edits
+ * on the Extensions page, a hook on record writes, a scheduled job, and a route.
+ * The Extensions registry sheet lists each of them once the API loads this file.
+ */
+
+/** Creates seen since the last daily summary, per collection. In memory: a
+ *  restart starts the count again, which is fine for a summary line. */
+const ${counter} = new Map<string, number>()
+
+export default defineExtension({
+  id: '${id}',
+  settings: [
+    {
+      key: 'greeting',
+      label: 'Greeting',
+      type: 'string',
+      default: 'Hello',
+      description: 'The word GET /api/${id}/hello answers with.'
+    }
+  ],
+  async register(ctx) {
+    const { app, auth, hooks, cron, logger } = ctx
+
+    // Route. \`preHandler: auth.requireAuth\` is the gate: the loader records it,
+    // and a route with no gate is a warning on the readiness scorecard.
+    app.register(
+      async (f) => {
+        f.get('/${id}/hello', { preHandler: auth.requireAuth }, async () => {
+          const greeting = (await ctx.settings?.get('greeting')) ?? 'Hello'
+          return { data: { message: \`\${greeting} from ${id}\` } }
+        })
+      },
+      { prefix: '/api' }
+    )
+
+    // Hook. After-hooks run once the write has landed; keep them quick, the
+    // caller waits for them.
+    hooks.after('*', 'create', async ({ collection }) => {
+      ${counter}.set(collection, (${counter}.get(collection) ?? 0) + 1)
+    })
+
+    // Scheduled job. The id is scoped to this extension; the description is
+    // what Background Jobs shows beside it.
+    cron.schedule(
+      'daily-summary',
+      '0 6 * * *',
+      async () => {
+        const total = [...${counter}.values()].reduce((n, v) => n + v, 0)
+        const busiest = [...${counter}.entries()].sort((a, b) => b[1] - a[1])[0]
+        ${counter}.clear()
+        await ctx.logActivity({
+          action: 'daily-summary',
+          comment: busiest
+            ? \`\${total} record(s) created; most in \${busiest[0]} (\${busiest[1]})\`
+            : 'No records created'
+        })
+        logger.info({ total }, '${id}: daily summary written')
+      },
+      {
+        description: 'One activity line a day counting the records created since the last.',
+        idempotent: 'safe'
+      }
+    )
+  }
+})
+`
+
+  const test = `import { createTestContext } from '@nivaro/extension-kit'
+import { describe, expect, it } from 'vitest'
+import extension from './index.js'
+
+describe('${id}', () => {
+  it('answers the hello route with the configured greeting', async () => {
+    const ctx = createTestContext({ settings: { greeting: 'Hi' } })
+    await extension.register(ctx)
+    const res = await ctx.invoke('GET', '/api/${id}/hello')
+    expect(res).toEqual({ status: 200, body: { data: { message: 'Hi from ${id}' } } })
+  })
+
+  it('counts creates and reports them from the daily job', async () => {
+    const ctx = createTestContext()
+    await extension.register(ctx)
+    await ctx.runHooks('orders', 'create', 'after', { keys: [1] })
+    await ctx.runHooks('orders', 'create', 'after', { keys: [2] })
+    await ctx.runCron('daily-summary')
+    expect(ctx.calls.activity).toEqual([
+      { action: 'daily-summary', comment: '2 record(s) created; most in orders (2)' }
+    ])
+    expect(ctx.registered.crons.get('daily-summary')?.opts?.description).toBeTruthy()
+  })
+
+  it('uses no deprecated kit member', async () => {
+    const ctx = createTestContext()
+    await extension.register(ctx)
+    expect(ctx.calls.deprecations).toEqual([])
+  })
+})
+`
+
+  const readme = `# ${label}
+
+Scaffolded by \`nivaro ext init ${id}\`. The API loads it from \`api/extensions/${id}/\` at boot
+(restart the API after adding it); the Extensions page lists it with a registry sheet of
+everything it registered.
+
+## What it registers
+
+| Thing | Where | Context member |
+|---|---|---|
+| Setting \`greeting\` | Extensions page → ${id} → Settings | \`settings\` on the export, read with \`ctx.settings.get('greeting')\` |
+| Route \`GET /api/${id}/hello\` | behind \`requireAuth\` | \`ctx.app.register\`, gated with \`ctx.auth.requireAuth\` |
+| Hook after every create | all collections | \`ctx.hooks.after('*', 'create', fn)\` |
+| Daily job \`daily-summary\` | Background Jobs | \`ctx.cron.schedule(id, expression, fn, { description })\` |
+| Activity line | Activity log | \`ctx.logActivity({ action, comment })\` |
+
+## Context members you will reach for next
+
+- \`ctx.database\` — knex on the instance database (raw writes skip hooks, revisions and permissions; prefer the items API for record writes).
+- \`ctx.notifyUser(userId, { subject, message })\` — the only way to notify a person.
+- \`ctx.callExternalApi(name, { method, path, body })\` — configured external APIs; credentials never reach the extension.
+- \`ctx.flows.registerOperation\` / \`registerTrigger\` / \`emit\` — custom flow steps and triggers.
+- \`ctx.readiness.registerCheck\`, \`ctx.integrity.registerCheck\` — scored checks and Data Integrity checks.
+- \`ctx.events.publish\` / \`on\` — a durable outbox for this extension's own events.
+- \`ctx.sql.runLong(sql)\` — one long statement outside knex's request timeout.
+
+The full contract is \`ExtensionContext\` in \`@nivaro/extension-kit\`.
+
+## Test and type-check
+
+\`\`\`bash
+cd api
+npx vitest run extensions/${id}
+npx tsc -p extensions/tsconfig.json
+\`\`\`
+
+The test runs the extension against the kit's \`createTestContext()\`: every side effect lands in
+\`ctx.calls\`, every registration in \`ctx.registered\`, and \`ctx.calls.deprecations\` lists any
+deprecated kit member the extension read.
+`
+
+  return { 'index.ts': index, 'index.test.ts': test, 'README.md': readme }
+}
+
+/**
+ * Writes the extension. Throws (with the reason) on a bad id or an existing
+ * directory; answers the paths written.
+ */
+export function writeScaffold(id, dir) {
+  const bad = validateExtensionId(id)
+  if (bad) throw new Error(bad)
+  if (typeof dir !== 'string' || dir.length === 0 || dir.includes('\0'))
+    throw new Error('--dir must be a directory path')
+  const base = resolve(dir)
+  const target = join(base, id)
+  // The extension lands exactly one level under --dir, never beside or above it.
+  const rel = relative(base, target)
+  if (rel !== id || isAbsolute(rel)) throw new Error(`Refusing to write outside ${base}`)
+  if (existsSync(target)) throw new Error(`${target} already exists — pick another id or remove it`)
+  mkdirSync(target, { recursive: true })
+  const written = []
+  for (const [name, text] of Object.entries(scaffoldFiles(id))) {
+    const file = join(target, name)
+    writeFileSync(file, text, 'utf8')
+    written.push(file)
+  }
+  return { target, written, hasTsconfig: existsSync(join(base, 'tsconfig.json')) }
+}