@usemo.com/sdk 0.1.0

package/README.md

@@ -0,0 +1,233 @@
+# UseMo CLI, JavaScript client and MCP
+
+Create videos, images, written content, social posts, articles and decks from a
+terminal or an AI agent. Node.js 20 or newer is required. The package includes
+`usemo` and `usemo-mcp`; neither needs Python, the backend, or a local database.
+
+## Install
+
+```bash
+npm install -g @usemo.com/sdk@0.1.0
+usemo --version
+usemo --help
+```
+
+For a one-off command without a global install:
+
+```bash
+npx --yes --package @usemo.com/sdk@0.1.0 usemo --help
+```
+
+## Install from this repository
+
+```bash
+cd sdk/javascript
+npm ci
+npm install -g .
+usemo --version
+usemo --help
+```
+
+To distribute the client without the backend, run `npm pack` in this directory
+and install the resulting tarball with `npm install -g /path/to/usemo-sdk-0.1.0.tgz`.
+The package contains only client source, its generated schemas, and this guide.
+
+## Authenticate
+
+Create a workspace key in **UseMo → Settings → API Keys**. Supply it through
+`USEMO_API_KEY` from your secret manager. To save an existing key as a local profile:
+
+```bash
+printf '%s\n' "$USEMO_API_KEY" | usemo login --key-stdin --profile work
+usemo whoami --profile work --json
+usemo profiles list
+usemo profiles use work
+```
+
+Login verifies the key with a workspace read before saving it. It does not
+create an account or a key. Browser/device login is not implemented in this CLI.
+The existing hosted MCP connector has its own OAuth flow when enabled by the deployment.
+
+Profiles are stored as plaintext in `~/.config/usemo/config.json`, with directory
+mode `0700` and file mode `0600`. Override the directory with `USEMO_CONFIG_DIR`
+or `XDG_CONFIG_HOME`. Environment keys take precedence over the selected profile.
+`--profile` takes precedence over `USEMO_PROFILE`, then the saved active profile.
+`--base-url` takes precedence over `USEMO_API_BASE`, then the profile's base URL,
+then `https://api.usemo.com`. `/api` and `/api/v1` suffixes are accepted.
+
+Saved keys are bound to their original host: changing the API host requires a
+separate login/profile or explicitly supplying `USEMO_API_KEY`. HTTPS is required
+except for loopback development. Keys are sent through `X-API-Key`, matching the
+current REST implementation. `USEMO_WORKSPACE_ID` is optional for a scoped API key.
+`usemo logout` removes the selected local profile; revoke keys separately in the app.
+
+## Create media and content
+
+```bash
+# Validate and inspect the request without credentials or API calls
+usemo images create "A green ceramic vase in a sunlit studio" --dry-run --json
+
+# Create an image and wait for its result URLs
+usemo images create "A green ceramic vase in a sunlit studio" --wait --json
+
+# Brief → grounded storyboard → finished video
+usemo videos create "A 30-second product launch video for our brand" --wait --json
+
+# Animate an existing frame (use an actual image URL or asset ID)
+usemo videos generate "A slow camera push toward the product" \
+  --input-image-url https://example.com/product.png --duration-sec 5 --wait --json
+
+usemo content create "Write a LinkedIn post announcing our launch" --wait --json
+usemo content social "Meet our new product" --cta "Explore now" --wait --json
+usemo content article "How to choose a team phone system" --wait --json
+usemo content deck "Product launch" --brief "Overview, audience, benefits and next steps" --wait --json
+```
+
+Generation spends workspace credits. Commands execute the requested operation
+without interactive confirmation. Use `--dry-run` to review a request. A video
+brief uses asynchronous planning by default to avoid gateway timeouts. It may
+initially return `planning: true`, `shippable: null`, and a job handle. A synchronous
+brief (`--async-plan=false`) can return `shippable: false` when the grounding gate blocks it; that is a
+planning result and no render job has been submitted. Refine the brief or brand
+context. Written content may return synchronously, or return a nested job handle;
+`--wait` handles both forms. Other creation responses contain asynchronous jobs.
+
+```bash
+usemo brand get --json
+usemo brand learn https://example.com --wait --json
+usemo ideas suggest "Announce our new product" --json
+usemo videos plan "A 30-second launch video" --json
+usemo videos quote --data @quote.json --json
+usemo jobs list --status processing --json
+usemo jobs get JOB_ID --json
+usemo jobs wait JOB_ID --max-wait-sec 600 --json
+usemo assets list --type image --json
+usemo twins list --json
+```
+
+For a quote, `quote.json` contains `{"storyboard": ...}` using the actual storyboard
+returned by planning. `campaigns quote` accepts a `concepts` array. Twin rendering
+uses `twins render TWIN_ID --audio-asset-id AUDIO_ID`; voice generation uses
+`twins speak TWIN_ID --script-text "Your script"`.
+
+## Agent and automation contract
+
+- `usemo schema [GROUP COMMAND] --json` provides input JSON Schema, descriptions,
+  annotations and routes. `usemo discover QUERY --json` searches the command catalog.
+- Field flags use dashes (`--num-images`); JSON uses underscores (`num_images`).
+  Nested objects/arrays can be supplied as JSON flags or through `--data`.
+- `--data` accepts an inline object, `@file.json`, or `@-` for stdin. Duplicate
+  flags and duplicate fields between JSON and flags are rejected.
+- `--json` emits a single JSON value on stdout. Errors are JSON on stderr.
+  Exit codes: `0` success, `1` API/auth/network/local error, `2` invalid input,
+  `3` wait timeout, `4` failed/cancelled job. `shippable: false` is a successful
+  planning response; inspect it before assuming media was generated.
+- `--out receipt.json` saves JSON without overwriting an existing file.
+  Use `usemo download HTTPS_URL --out video.mp4` to download a result URL.
+  Downloads stream to a temporary file and publish atomically, do not overwrite,
+  and never send an API key to the media host. Redirecting asset URLs are rejected;
+  retrieve a direct URL from the library if necessary.
+- Submission timeout defaults to 60 seconds (`--timeout`). Waiting defaults to
+  180 seconds and polls every 5 seconds (`--wait-timeout`, `--poll-interval`).
+  The explicit `jobs wait` tool supports `max_wait_sec` 5–600 and
+  `poll_interval_sec` 2–30. A wait timeout leaves the remote job running and returns
+  its handle. Resume waiting instead of resubmitting.
+- Image generation, direct video generation, video creation and text generation
+  accept `--idempotency-key`. The client generates one if omitted and includes it
+  in the receipt or ambiguous-submission error. Reuse the same key **and payload**
+  for a retry. No requests are automatically retried. Other endpoints are not
+  assumed to implement idempotency.
+- `doctor` is an offline configuration check and does not print secrets.
+  `whoami` verifies access through the brand-profile endpoint; it does not claim
+  to return a complete identity/scopes record.
+
+For API capabilities outside the curated catalog:
+
+```bash
+usemo request GET /api/v1/assets --query job_id=JOB_ID --query offset=20 --json
+usemo request POST /api/v1/jobs/JOB_ID/cancel --dry-run --json
+```
+
+Generic requests use the selected API origin only. Read the current REST schema
+for advanced payloads. CLI dry runs validate curated inputs, but cannot verify
+server permissions, available credits, remote asset URLs, or runtime model health.
+
+## Connect MCP
+
+Without a global installation, configure your MCP client to launch the npm package:
+
+```json
+{
+  "mcpServers": {
+    "usemo": {
+      "command": "npx",
+      "args": ["--yes", "--package", "@usemo.com/sdk@0.1.0", "usemo-mcp"],
+      "env": { "USEMO_PROFILE": "work" }
+    }
+  }
+}
+```
+
+With the package globally installed, configure an MCP client to launch:
+
+```json
+{
+  "mcpServers": {
+    "usemo": {
+      "command": "usemo-mcp",
+      "env": { "USEMO_PROFILE": "work" }
+    }
+  }
+}
+```
+
+A saved profile or a `USEMO_API_KEY` supplied by the host provides authentication.
+If a GUI cannot resolve the executable on PATH, use its absolute installed path,
+or `node` with the absolute path to this package's `src/mcp.js`.
+`usemo mcp --profile work` is the equivalent CLI entry point. Protocol messages
+are the only stdout output. The server exposes 24 tools, including offline
+`usemo_get_started` and `usemo_discover_tools`. Local tool inputs are flat objects
+as advertised by `tools/list`; follow the actual schema exposed by your transport.
+
+The existing remote connector remains at `https://api.usemo.com/mcp`:
+
+```json
+{
+  "mcpServers": {
+    "usemo": { "url": "https://api.usemo.com/mcp" }
+  }
+}
+```
+
+Remote clients must supply their own API key or complete the deployment's OAuth
+flow. Enabling OAuth and deploying backend changes are separate release steps.
+New tools in this checkout are not available on the hosted endpoint until deployed.
+
+## JavaScript API
+
+```js
+import { UseMoClient } from '@usemo.com/sdk';
+
+const usemo = new UseMoClient({ apiKey: process.env.USEMO_API_KEY });
+const result = await usemo.run('images create', {
+  prompt: 'A green ceramic vase in a sunlit studio',
+  idempotency_key: 'my-unique-workflow-step-id'
+}, { wait: true, timeout: 300 });
+console.log(result);
+```
+
+## Development and release checks
+
+```bash
+npm ci
+npm test
+# From the repository root, using its development Python environment:
+.venv/bin/python sdk/javascript/scripts/export_catalog.py --check
+```
+
+The catalog is generated from `app/mcp/tools.py` and the public collateral
+request models. After changing those inputs, regenerate it with the same command
+without `--check`. CI verifies that the checked-in catalog stays current.
+Tests use mocked HTTP, a loopback API, and actual MCP SDK transports; they do not
+spend credits or render real media. Validate a release with a real workspace key
+and representative generations before publishing to npm and deploying the hosted tools.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@usemo.com/sdk",
+  "version": "0.1.0",
+  "description": "UseMo CLI, JavaScript client and MCP server for videos, images and content.",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "usemo": "src/cli.js",
+    "usemo-mcp": "src/mcp.js"
+  },
+  "exports": {
+    ".": "./src/client.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "check:catalog": "python scripts/export_catalog.py --check",
+    "prepack": "npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "zod": "^3.25.76"
+  },
+  "homepage": "https://usemo.com",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "usemo",
+    "mcp",
+    "cli",
+    "ai-video",
+    "image-generation",
+    "content-generation"
+  ]
+}