@convilyn/sdk-author 0.7.0

package/README.md

@@ -0,0 +1,310 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/CoreNovus/convilyn-author-js/main/docs/assets/corenovus-community-banner.png" alt="CoreNovus Community — Connected AI Workflows" />
+</p>
+
+# @convilyn/sdk-author
+
+[![CI](https://github.com/CoreNovus/convilyn-author-js/actions/workflows/ci.yml/badge.svg)](https://github.com/CoreNovus/convilyn-author-js/actions/workflows/ci.yml)
+
+Official Convilyn **Author SDK** for TypeScript / JavaScript — build and host
+tool servers, author workflow specs, and create reusable AI workflow components
+for the Convilyn AI platform. The counterpart to the consumer SDK
+[`@convilyn/sdk`](https://www.npmjs.com/package/@convilyn/sdk): where the
+consumer SDK *calls* Convilyn with a `ck_` key, the Author SDK lets you *extend*
+the platform — authoring tools and workflows that the gateway calls back into,
+secured by HMAC. The wire shapes match Convilyn's gateway and authoring APIs
+exactly.
+
+Convilyn Author helps builders turn tools, services, and repeated processes into
+reusable workflow building blocks. It is part of the CoreNovus vision for
+practical AI workflows across cloud services, local machines, AI PCs, edge
+devices, and future IoT environments.
+
+> **Public mirror** of Convilyn's monorepo (the source of truth). Contributions
+> are welcome and land in the shipped package — see
+> **[CONTRIBUTING.md](CONTRIBUTING.md)** (fork → PR → upstreamed, authorship
+> preserved).
+
+> **Status: feature-complete surface (0.x).** Ships the tool-server foundation,
+> the `WorkflowSpec` builder, the `ToolServer` + JSON-RPC `/mcp` runtime, the
+> `convilyn-author` CLI, confirmation-token signing, and the `ConvilynClient`
+> platform client + local test harness. Only what is documented here is exported
+> and covered by SemVer; while `0.x`, minor versions may still adjust the surface.
+
+## Install
+
+```bash
+npm install @convilyn/sdk-author
+```
+
+Node 18+ (uses `node:crypto`). Ships ESM + CJS + type declarations. Runtime
+dependencies are minimal — `commander` (CLI) and `zod-to-json-schema` — plus
+`zod` as a peer dependency.
+
+## Tool-server foundation
+
+### HMAC inbound verification
+
+The gateway signs every call it makes to your tool server; verify the signature
+to reject forged requests (use this if you run your own HTTP framework — the
+SDK's built-in runtime, `serve`, does it for you).
+
+```ts
+import { verifySignature, InvalidSignatureError } from '@convilyn/sdk-author'
+
+try {
+  // `verifySignature` reads the `x-convilyn-signature` / `-timestamp` headers.
+  verifySignature(
+    process.env.CONVILYN_HMAC_SECRET!,
+    rawBodyBytes,
+    req.headers as Record<string, string | undefined>,
+  )
+  // ...handle the verified request
+} catch (err) {
+  if (err instanceof InvalidSignatureError) {
+    // err.reason ∈ missing_secret | missing_header | invalid_timestamp |
+    //              timestamp_out_of_range | signature_mismatch
+    res.writeHead(401).end()
+  }
+}
+```
+
+`signRequest(secret, body, unixSeconds)` produces the matching
+`{ signature, timestamp }` pair — for tests, or for calling a developer-hosted
+server directly.
+
+### Manifest, data store, context, config
+
+```ts
+import { ConvilynManifest, InMemoryDataStore, ToolResult, SDKConfig } from '@convilyn/sdk-author'
+
+const manifest = new ConvilynManifest(
+  { name: 'weather', version: '1.0.0', description: 'Weather tools' },
+  {
+    tools: [
+      {
+        name: 'get_weather',
+        description: 'Get current weather',
+        inputSchema: { type: 'object', properties: { location: { type: 'string' } } },
+        idempotent: true,
+      },
+    ],
+  }
+)
+await manifest.save('convilyn.manifest.json')
+
+const store = new InMemoryDataStore()
+const refId = await store.store({ large: 'payload' }) // → "td_<12-hex>"
+
+const result = ToolResult.ok({ refId, summary: 'Weather for Taipei' })
+
+const config = SDKConfig.fromEnv() // reads CONVILYN_* env vars
+```
+
+Tools return `{ ref_id, summary }` (build with `ToolResult.ok(...)` /
+`ToolResult.fail(...)`) so the agent's context stays small and fetches the full
+data by `ref_id` later.
+
+## Workflow authoring
+
+`WorkflowSpec` is an immutable fluent builder for a portable workflow — a
+`specId` (the portal's `dev_<developer-id>.<name>` namespace), a name, a system
+prompt, and a palette of `"server:tool"` references. It validates client-side
+as you build (name ≤80, ≤20 tools, semver version, rejects the
+`request_user_input` tool, …) and has one method per wire contract:
+
+- `compile()` → the snake_case **`WorkflowBlueprint`** publish artifact
+  (`spec_id`/`version`/`public_schema_version`; cross-SDK parity with the
+  Python author SDK) — what `submitWorkflow` / `push` send to the portal.
+- `toExportPayload()` → the camelCase user_workflows **`ExportPayload`**
+  (canvas/authoring contract; carries UI-only positions/notes/canvasLayout).
+
+```ts
+import { WorkflowSpec, buildWorkflowPolicies } from '@convilyn/sdk-author'
+
+const spec = new WorkflowSpec('Invoice summariser', { specId: 'dev_abc123.invoice_summariser' })
+  .withDescription('Extracts totals from invoices')
+  .withSystemPrompt('You summarise invoices into a totals table.')
+  .useTools('doc-parser-mcp:extract_text', 'doc-parser-mcp:extract_tables')
+  .withTags(['finance'])
+
+await spec.save('workflow.spec.json') // portable WorkflowBlueprint JSON
+const reloaded = await WorkflowSpec.load('workflow.spec.json') // loads blueprint OR ExportPayload
+
+// Optional high-level policies (attached when publishing a workflow):
+const policies = buildWorkflowPolicies({
+  retry: { maxAttempts: 3, retryOn: ['transient'] },
+  timeout: { maxStepCount: 12 },
+})
+
+// Compile the blueprint locally, then publish it through the Developer Portal:
+const compiled = spec.compile() // → pass to client.submitWorkflow({ workflow_spec, server_ids })
+```
+
+## Tool server
+
+`defineTool` declares a tool from a [Zod](https://zod.dev/) schema — the single
+source of truth for the manifest `input_schema`, the handler's argument types,
+and runtime validation of inbound calls. `ToolServer` registers tools and
+`serve` runs the JSON-RPC `/mcp` runtime (`/health`, `/manifest`, and an
+HMAC-verified `POST /mcp`), interchangeable with the Python / Go author SDKs
+behind the same gateway. `zod` is a peerDependency — install it alongside the
+SDK and `import { z } from 'zod'` yourself.
+
+```ts
+import { defineTool, ToolServer, ToolResult, serve } from '@convilyn/sdk-author'
+import { z } from 'zod'
+
+const echo = defineTool({
+  name: 'echo',
+  description: 'Echo the input text back.',
+  input: z.object({ text: z.string().min(1) }),
+  idempotent: true,
+  handler: (args) => ToolResult.ok({ echoed: args.text }, `Echoed ${args.text.length} chars`),
+})
+
+const server = new ToolServer({ name: 'echo-server', version: '1.0.0', description: 'demo' })
+server.register(echo)
+
+// Run it (CONVILYN_HMAC_SECRET / CONVILYN_PORT come from the env via SDKConfig):
+serve(server, { port: 8080 })
+```
+
+## CLI
+
+The package ships a `convilyn-author` binary:
+
+```bash
+npx convilyn-author init my-server   # scaffold a TS project
+cd my-server && npm install && npm run build
+npx convilyn-author dev      # run the JSON-RPC /mcp server (serve)
+npx convilyn-author synth    # write convilyn.manifest.json
+npx convilyn-author test     # local compliance checks (runComplianceChecks)
+npx convilyn-author push --endpoint-url https://my-server.example.com  # publish
+```
+
+`synth` / `dev` / `test` load a **built** JS module (default `server.js`,
+override with `--file dist/server.js`) that exports a `ToolServer` as its default
+or a named `server` export.
+
+`push` submits your server + workflow to the **Developer Portal** (wrapping
+`ConvilynClient.submitServer` + `submitWorkflow`): set a `cvl_` key in
+`CONVILYN_API_KEY`, then `push --endpoint-url <https://...>` (the HTTPS URL where
+*you* host the server) with `--file` (built server, default `server.js`) and
+`--workflow-file` (a `workflow.spec.json` or a built module, default
+`workflow.spec.json`). The managed `deploy --hosted` provisions your server in
+the **Convilyn-Hosted Author Runtime** (no infrastructure of your own):
+`deploy --hosted [--region us-east-1]` hands over the manifest (plus the
+compiled workflow when `workflow.spec.json` exists), then `logs <runtimeId>`
+tails the runtime logs and `rollback <runtimeId>` flips back to the previous
+version. Without `--hosted`, `deploy` errors and points at
+`push --endpoint-url` (BYO). Both commands speak the same Developer Portal wire
+contract as `ConvilynClient`.
+
+## Developer Portal client
+
+`ConvilynClient` is a `fetch`-based client for the **Developer Portal**
+(`/api/v1/developers/*`) — the platform's third-party author/publish surface,
+mirroring the Python `convilyn-author` SDK. You **build and test your own** tool
+server + workflow locally (`ToolServer`, `WorkflowSpec`, `runComplianceChecks`),
+then **integrate** them by registering through the portal. Authenticate with a
+`cvl_` developer key as a Bearer token (`CONVILYN_API_KEY`); the base URL is
+`${CONVILYN_PLATFORM_URL}/api/v1`.
+
+> The SDK does **not** call the first-party console surfaces (`/user_workflows/*`,
+> `/mcp/tools/catalog`) — those are JWT/session endpoints owned by the web UI, not
+> an author-publishing API. Validate and cost-preview your work **locally** with
+> `runComplianceChecks` / `WorkflowSpec.compile` before submitting.
+
+```ts
+import { ConvilynClient, ToolServer, WorkflowSpec } from '@convilyn/sdk-author'
+
+// 1) Register once (no auth) → mint + capture a cvl_ key. Save it; shown once.
+const client = new ConvilynClient()
+const { api_key } = await client.register({ email: 'dev@example.com', name: 'Dev' })
+// …or pass an existing cvl_ key: new ConvilynClient({ apiKey: myCvlKey })
+// …or set it in the environment: export CONVILYN_API_KEY=cvl_your_key
+
+// 2) Submit your own tool server for verification.
+const server = await client.submitServer({
+  manifest: myToolServer.manifest().toWire(),
+  endpoint_url: 'https://my-server.example.com',
+})
+await client.testServer(server.server_id) // sandbox test
+await client.serverStatus(server.server_id) // → verified / active / rejected
+
+// 3) Submit your compiled workflow, referencing the server(s) it uses.
+const spec = new WorkflowSpec('Invoice summariser', { specId: 'dev_abc123.invoice_summariser' })
+  .withSystemPrompt('…')
+  .useTools('my-server:extract_text')
+const wf = await client.submitWorkflow({ workflow_spec: spec.compile(), server_ids: [server.server_id] })
+await client.testWorkflow(wf.workflow_id)
+```
+
+Also available: `listServers` / `deactivateServer`, `listWorkflows` /
+`workflowStatus` / `deactivateWorkflow`, and the hosted-runtime surface
+`deployHostedRuntime` / `rollbackHostedRuntime` / `getHostedRuntimeLogs`.
+A non-2xx response throws
+`ConvilynApiError` (with `.status` and `.body`); an authed call with no key throws
+`ConvilynAuthorError` before any network call.
+
+## Confirmation tokens
+
+For tools that require a human confirmation handshake, the SDK signs and verifies
+confirmation tokens byte-for-byte compatibly with the gateway and the Python / Go
+author SDKs:
+
+```ts
+import { mintConfirmationToken, verifyConfirmationToken, CONFIRMATION_TTL_SECONDS } from '@convilyn/sdk-author'
+
+const secret = process.env.CONVILYN_TOOL_CONFIRMATION_SECRET!
+const expiresAtUnix = Math.floor(Date.now() / 1000) + CONFIRMATION_TTL_SECONDS
+const token = mintConfirmationToken({ toolName: 'submit_order', arguments: args, expiresAtUnix, secret })
+
+// On the confirming re-call, with `confirmation_token` present in arguments:
+verifyConfirmationToken({ toolName: 'submit_order', arguments: argsWithToken, token, secret })
+// throws ConfirmationInvalidError on a malformed / expired / mismatched token
+```
+
+The argument digest strips volatile presigned-URL params, so a re-presigned URL
+still matches the originally-confirmed arguments.
+
+## Local testing harness
+
+`invokeTool` drives a `ToolServer` in-process (no HTTP), returning the same wire
+envelope the gateway would receive — ideal for unit tests:
+
+```ts
+import { invokeTool } from '@convilyn/sdk-author'
+
+const wire = await invokeTool(server, 'echo', { text: 'hi' })
+expect(wire.status).toBe('ok')
+expect(wire.data).toEqual({ echoed: 'hi' })
+```
+
+## Authentication at a glance
+
+| Secret (env) | Used for |
+|---|---|
+| `CONVILYN_API_KEY` | `cvl_` developer key — Bearer auth to the Developer Portal (`ConvilynClient`) |
+| `CONVILYN_HMAC_SECRET` | Verifying inbound `POST /mcp` calls from the gateway (`serve` / `verifySignature`) |
+| `CONVILYN_TOOL_CONFIRMATION_SECRET` | Minting / verifying confirmation tokens |
+
+## Getting a runnable starter
+
+`npx convilyn-author init my-server` scaffolds a complete TypeScript
+tool-server project (`server.ts`, build config, `.env.example`) — the fastest
+way to see the tool server, manifest, and compliance checks working together.
+
+## Public API & Stability
+
+This package follows [Semantic Versioning](https://semver.org/). **The SemVer
+contract is exactly the set of names exported from the package root**; anything
+not exported there is internal and may change in any release. The `package.json`
+`exports` map blocks deep imports, and a packaging test pins the public surface.
+While the package is `0.x` (pre-1.0), minor versions may still contain breaking
+changes as the surface stabilises toward 1.0.
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).