@noimosai/platform-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AGOS Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/USAGE.md

@@ -0,0 +1,103 @@
+# NoimosAI Platform CLI
+
+Command-line access to the NoimosAI Developer Platform.
+Requires Node.js 22 or later.
+
+~~~bash
+npm install -g @noimosai/platform-cli
+noimos-platform --help
+~~~
+
+Without a global install: npx -y @noimosai/platform-cli --help.
+
+Set NOIMOS_PLATFORM_API_URL to the tool API URL shown in the developer console
+(ending in /noimosToolBridge) and NOIMOS_PLATFORM_API_KEY to your dedicated
+developer key. Never commit the key to a repository.
+
+~~~bash
+noimos-platform tools --summary
+noimos-platform tool web_search
+noimos-platform quote web_search '{"query":"content marketing"}'
+noimos-platform help execute
+~~~
+
+Execution requires the quote's price version and maximum charge, plus a retained
+idempotency key. Retry an uncertain submission with the same arguments and key.
+Use execution, executions, wait, and download to recover results.
+Discovery and quotes do not start paid work.
+
+## Media understanding and transcription
+
+Use analyze_video for agentic video understanding, analyze_image for image/OCR
+questions, analyze_audio for sound/music/speech questions, and transcribe_audio
+for verbatim text, speaker labels and word timestamps with SRT/VTT strings.
+Inspect each tool's current schema and availability with `tool <name>`.
+
+~~~bash
+noimos-platform upload ./interview.wav
+noimos-platform tool transcribe_audio
+noimos-platform quote analyze_video '{"source":{"url":"https://www.youtube.com/watch?v=LuIL5JATZsc"},"question":"Describe the key scenes with timestamps."}'
+~~~
+
+Use the upload response's `data.id` as `source.fileId`. Inputs may alternatively
+reference a project artifact with `source.executionId` and `source.artifactId`.
+Uploads accept explicitly selected regular JPG/PNG/WAV/MP3/MP4 files up to 12 MiB,
+are private to the developer project and expire after 30 days. Public HTTPS media
+URLs use the same size bound; public YouTube video URLs are passed to the analysis
+service. Uploads do not start inference. Quotes reserve input/output token limits;
+adaptive video processing can exceed the reservation and require review, without
+automatically charging above the accepted maximum. Use local tools such as FFmpeg
+for conversion, trimming, merging and subtitle rendering.
+
+## Reference generation and voice isolation
+
+Use generate_image with referenceImages and describe the desired edit in prompt.
+Each image is a {fileId}, {executionId, artifactId}, or {url} object. Upload a local
+image first, then use its returned ID. Gemini and both GPT Image models support
+the same input contract; inspect the catalog for current models and prices.
+
+~~~bash
+noimos-platform upload ./product.png
+noimos-platform quote generate_image '{"prompt":"Keep the product; change the background to a bright kitchen.","referenceImages":[{"fileId":"f_<SHA-256>"}]}'
+noimos-platform quote generate_video '{"prompt":"Slow camera move around the product.","firstFrame":{"fileId":"f_<SHA-256>"},"duration":5}'
+noimos-platform quote isolate_voice '{"source":{"fileId":"f_<SHA-256>"},"maxDurationSeconds":60}'
+~~~
+
+Replace the placeholder IDs with upload results. Image/video references accept
+up to four ordered JPG/PNG images, 12 MiB combined. Video accepts referenceImages
+or firstFrame with optional lastFrame; omit aspectRatio in frame mode. Reuse a
+generated artifact as input for further edits without downloading/uploading it.
+
+isolate_voice removes background noise from speech. It accepts PCM WAV or MPEG-1
+Layer III MP3 at 44.1 kHz/128 kbps, up to 12 MiB and 600 seconds. It bills the full
+input duration including silence; unused duration reservation is returned.
+Availability and the configured per-minute price are returned by the catalog.
+
+## MCP
+
+The MCP server is a separate package: @noimosai/platform-mcp.
+Configure your host to launch npx with arguments
+["-y", "@noimosai/platform-mcp"], passing the two environment variables above.
+Pin a tested package version in managed installations.
+
+~~~json
+{
+  "mcpServers": {
+    "noimos-platform": {
+      "command": "npx",
+      "args": ["-y", "@noimosai/platform-mcp"],
+      "env": {
+        "NOIMOS_PLATFORM_API_URL": "https://YOUR_API_HOST/noimosToolBridge",
+        "NOIMOS_PLATFORM_API_KEY": "YOUR_DEVELOPER_API_KEY"
+      }
+    }
+  }
+}
+~~~
+
+This package uses developer projects and USD balances. It does not use the
+workspace credentials, social connections or credits of the NoimosAI app.
+For workspace operations, use the separate @noimosai/cli or @noimosai/mcp.
+
+Local emulators only: set NOIMOS_PLATFORM_ENV=local to allow loopback HTTP.
+The MCP transport is stdio; this package does not start a hosted HTTP endpoint.

package/bin/noimos-platform.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+
+const args = process.argv.slice(2);
+if (args.length === 1 && args[0] === "--version") {
+  const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  console.log(manifest.version);
+} else {
+  const { runCli } = await import("../dist/cli/cli.js");
+  process.exitCode = await runCli(args, process.env, console.log, console.error);
+}

package/dist/cli/cli.js

@@ -0,0 +1,177 @@
+import { parseArgs } from "node:util";
+import { createReadStream } from "node:fs";
+import { configFromEnvironment, PlatformClient, platformToolInputSchema, platformCreateExecutionSchema, platformArtifactIdSchema, platformExecutionListQuerySchema, platformToolDiscoverySchema } from "../client/index.js";
+import { downloadArtifact } from "./download.js";
+import { commandHelp } from "./command-help.js";
+import { uploadLocalInput } from "../client/local-input.js";
+export const help = `NoimosAI Developer Platform CLI
+
+Usage: noimos-platform <command>
+       noimos-platform <command> --help | help <command>
+
+  project    Show the developer organization and project bound to the API key
+  usage      Show the current project's monthly request count and spend
+  tools [--query <text>] [--category <research|seo|social|generation>]
+        [--available-only] [--summary]
+             List tools and USD prices; summary omits schemas and examples
+  tool <name>
+             Inspect one tool's arguments, example and price
+  executions [--limit <1-100>] [--before <id>] [--status <state>] [--tool <name>]
+             Recover the API key's project execution history
+  quote <tool> '<arguments-json>'
+             Get a free quote without running the tool
+  execute <tool> '<arguments-json>' --maximum-charge-micros <integer>
+          --price-version <version> --idempotency-key <uuid>
+             Reserve up to the quoted amount and enqueue paid work
+  execution <id>
+             Read status, output and the final USD charge
+  wait <id> [--timeout <seconds>]
+             Wait for completion (default 480 seconds, maximum 900)
+  cancel <id>
+             Request cancellation of work that has not started
+  artifact-url <execution-id> <artifact-id>
+             Get a private output's download URL, valid for up to 5 minutes
+  download <execution-id> <artifact-id> --out <file>
+             Save an artifact after size/SHA-256 checks; never overwrite a file
+  upload <file>
+             Upload one explicit JPG/PNG/WAV/MP3/MP4 input, at most 12 MiB
+
+Get a quote first. Use its price version and maximum charge (1 USD = 1000000
+micros). Keep the same body and idempotency key when retrying a submission.
+Execution is asynchronous. Poll at intervals of at least 5 seconds.
+Use - in place of arguments-json to read JSON from stdin (at most 64 KiB).
+Use --input-file <path> in place of arguments-json to read a JSON file.
+wait exits 0 on success, 1 on failed/cancelled/needs_review, 3 on timeout.
+A timeout leaves accepted work running; read or wait on the same execution ID.
+
+Standalone tools only: no workspace, brand, knowledge base, dataset, connected
+provider account, post, workspace skill or chat-session commands. Scope comes
+from the developer API key; supply prompts, public URLs, project files or artifacts.
+
+Environment: NOIMOS_PLATFORM_API_URL, NOIMOS_PLATFORM_API_KEY
+Local emulators only: NOIMOS_PLATFORM_ENV=local
+
+Manage organizations, members, keys and billing at platform.noimosai.com.
+`;
+export async function runCli(args, env, output, error, transport = fetch, stdin = process.stdin) {
+    if (!args.length || args[0] === "--help" || args[0] === "-h" || args.length === 1 && args[0] === "help") {
+        output(help);
+        return 0;
+    }
+    if (args[0] === "help" || args.slice(1).some((arg) => arg === "--help" || arg === "-h")) {
+        const detail = commandHelp(args[0] === "help" ? args[1] : args[0]);
+        if (!detail || args[0] === "help" && args.length !== 2) {
+            error("Unknown help command. Run noimos-platform --help.");
+            return 2;
+        }
+        output(detail);
+        return 0;
+    }
+    if (args.length === 1 && args[0] === "--version") {
+        output("0.1.0");
+        return 0;
+    }
+    let command;
+    let exitCode = 0;
+    try {
+        if (["quote", "execute"].includes(args[0]) && ["-", "--input-file"].includes(args[2])) {
+            const file = args[2] === "--input-file" ? args[3] : "-";
+            if (!file || file.startsWith("--"))
+                throw new Error("Provide an input file");
+            const source = file === "-" ? stdin : createReadStream(file);
+            const chunks = [];
+            let bytes = 0;
+            for await (const chunk of source) {
+                const buffer = Buffer.from(chunk);
+                bytes += buffer.byteLength;
+                if (bytes > 65536)
+                    throw new Error("Input exceeds 64 KiB");
+                chunks.push(buffer);
+            }
+            args = [args[0], args[1], Buffer.concat(chunks).toString("utf8"), ...args.slice(args[2] === "--input-file" ? 4 : 3)];
+        }
+        if (args.length === 2 && args[0] === "upload" && args[1].trim())
+            command = (client) => uploadLocalInput(client, args[1]);
+        else if (args.length === 1 && args[0] === "project")
+            command = (client) => client.project();
+        else if (args.length === 1 && args[0] === "usage")
+            command = (client) => client.usage();
+        else if (args[0] === "tools") {
+            const { values, tokens } = parseArgs({ args: args.slice(1), tokens: true, options: {
+                    query: { type: "string" }, category: { type: "string" }, "available-only": { type: "boolean" }, summary: { type: "boolean" },
+                } });
+            const names = tokens.filter((token) => token.kind === "option").map((token) => token.name);
+            if (new Set(names).size !== names.length)
+                throw new Error("Duplicate discovery option");
+            const input = platformToolDiscoverySchema.parse({ query: values.query, category: values.category, availableOnly: values["available-only"], summary: values.summary });
+            command = (client) => client.discoverTools(input);
+        }
+        else if (args.length === 2 && args[0] === "tool" && /^[a-z][a-z0-9_]{1,63}$/.test(args[1]))
+            command = (client) => client.tool(args[1]);
+        else if (args[0] === "executions" && args.length % 2 === 1) {
+            const flags = {};
+            for (let index = 1; index < args.length; index += 2) {
+                const name = args[index].slice(2);
+                if (!["--limit", "--before", "--status", "--tool"].includes(args[index]) || Object.hasOwn(flags, name))
+                    throw new Error("Invalid history flag");
+                flags[name] = name === "limit" ? Number(args[index + 1]) : args[index + 1];
+            }
+            const input = platformExecutionListQuerySchema.parse(flags);
+            command = (client) => client.executions(input);
+        }
+        else if (args[0] === "wait" && (args.length === 2 || args.length === 4 && args[2] === "--timeout") && /^[A-Za-z0-9_-]{1,128}$/.test(args[1])) {
+            const seconds = args.length === 4 ? Number(args[3]) : 480;
+            if (!Number.isInteger(seconds) || seconds < 1 || seconds > 900)
+                throw new Error("Invalid wait timeout");
+            command = async (client) => {
+                const result = await client.waitExecution(args[1], seconds * 1000);
+                exitCode = result.timedOut ? 3 : result.data?.status === "succeeded" ? 0 : 1;
+                return result;
+            };
+        }
+        else if (args.length === 2 && ["execution", "cancel"].includes(args[0]) && /^[A-Za-z0-9_-]{1,128}$/.test(args[1])) {
+            command = (client) => args[0] === "execution" ? client.execution(args[1]) : client.cancelExecution(args[1]);
+        }
+        else if (args.length === 5 && args[0] === "download" && args[3] === "--out" && args[4].trim() && /^[A-Za-z0-9_-]{1,128}$/.test(args[1])) {
+            const artifactId = platformArtifactIdSchema.parse(args[2]);
+            command = (client) => downloadArtifact(client, args[1], artifactId, args[4], transport);
+        }
+        else if (args.length === 3 && args[0] === "artifact-url" && /^[A-Za-z0-9_-]{1,128}$/.test(args[1])) {
+            const artifactId = platformArtifactIdSchema.parse(args[2]);
+            command = (client) => client.artifactDownload(args[1], artifactId);
+        }
+        else if (args.length === 3 && args[0] === "quote") {
+            const input = platformToolInputSchema.parse({ tool: args[1], arguments: JSON.parse(args[2]) });
+            command = (client) => client.quote(input);
+        }
+        else if (args.length === 9 && args[0] === "execute") {
+            const flags = new Map();
+            for (let index = 3; index < args.length; index += 2) {
+                if (!["--maximum-charge-micros", "--price-version", "--idempotency-key"].includes(args[index]) || flags.has(args[index]))
+                    throw new Error("Invalid flag");
+                flags.set(args[index], args[index + 1]);
+            }
+            const maximum = flags.get("--maximum-charge-micros"), idempotencyKey = flags.get("--idempotency-key");
+            if (!maximum || !/^\d+$/.test(maximum) || !idempotencyKey || !/^[A-Za-z0-9._:-]{8,128}$/.test(idempotencyKey))
+                throw new Error("Invalid execution confirmation");
+            const input = platformCreateExecutionSchema.parse({ tool: args[1], arguments: JSON.parse(args[2]), maximumChargeMicros: Number(maximum), priceVersion: flags.get("--price-version") });
+            command = (client) => client.createExecution(input, idempotencyKey);
+        }
+        else
+            throw new Error("Invalid command");
+    }
+    catch {
+        error(`Invalid command, JSON arguments or input file.\n\n${commandHelp(args[0]) ?? help}`);
+        return 2;
+    }
+    try {
+        const client = new PlatformClient(configFromEnvironment(env, "cli"), transport);
+        const result = await command(client);
+        output(JSON.stringify(result, null, 2));
+        return exitCode;
+    }
+    catch (failure) {
+        error(failure instanceof Error ? failure.message : "Platform request failed.");
+        return 1;
+    }
+}

package/dist/cli/command-help.js

@@ -0,0 +1,69 @@
+const inputHelp = `Supply one JSON object inline, use - for stdin, or use --input-file <path>.
+File/stdin input is limited to 64 KiB. --input-file - also reads stdin.`;
+const commands = {
+    upload: `upload <file>
+Upload one explicitly chosen local JPG/PNG/WAV/MP3/MP4, at most 12 MiB, to this project.
+Requires tools:execute. No generation charge. Returns a file ID valid for up to 30 days.
+Use {"source":{"fileId":"..."}} with an understanding or transcription tool.
+Repeating identical bytes reuses the same project file; it does not extend its expiry.
+File bytes and local paths are not included in command output.`,
+    project: `project
+Read the organization and project bound to the developer API key. Free.`,
+    usage: `usage
+Read this project's monthly requests and spend. amountCents is USD cents. Free.`,
+    tools: `tools [--query <text>] [--category <research|seo|social|generation>]
+                      [--available-only] [--summary]
+Search names/descriptions, filter by category or configured provider, and show USD prices.
+Use --summary to omit schemas/examples, then tool <name> for full details. Free.
+available=true does not override executionEnabled=false or key/budget limits.
+
+Example: noimos-platform tools --query search --available-only --summary`,
+    tool: `tool <name>
+Inspect one tool's full input schema, example, availability and USD price. Free.
+
+Example: noimos-platform tool web_search`,
+    executions: `executions [--limit <1-100>] [--before <id>] [--status <state>] [--tool <name>]
+Read project history, newest first. Use nextBefore as --before for the next page.
+States: queued, running, waiting, succeeded, failed, cancelled, needs_review. Free.
+
+Example: noimos-platform executions --status failed --limit 20`,
+    quote: `quote <tool> '<arguments-json>'
+Get a free quote without starting paid work. Returns priceVersion and maximumChargeMicros.
+${inputHelp}
+
+Examples:
+  noimos-platform quote web_search '{"query":"content marketing trends"}'
+  noimos-platform quote web_search --input-file brief.json`,
+    execute: `execute <tool> '<arguments-json>' --maximum-charge-micros <integer>
+                        --price-version <version> --idempotency-key <key>
+Enqueue paid work using an accepted quote. All three confirmation flags are required.
+1 USD = 1000000 micros. Retain the same body and key when retrying a submission.
+Keys: 8-128 letters, digits, periods, underscores, colons or hyphens.
+${inputHelp}
+Returns an execution ID. Read it with execution <id> or wait <id>; acceptance is not completion.
+
+Example (use the values from your quote and a saved key):
+  noimos-platform execute web_search --input-file brief.json \\
+    --maximum-charge-micros "$PLATFORM_QUOTED_MAXIMUM_MICROS" \\
+    --price-version "$PLATFORM_QUOTED_PRICE_VERSION" --idempotency-key "$PLATFORM_REQUEST_UUID"`,
+    execution: `execution <id>
+Read an execution's status, output and chargedMicros (1 USD = 1000000 micros). Free.
+A pending zero charge is not a free completion. For needs_review, contact support;
+do not automatically submit a replacement.`,
+    wait: `wait <id> [--timeout <seconds>]
+Wait for completion, polling every 5 seconds. Default timeout: 480 seconds; range: 1-900.
+Exits 0 on success, 1 on failed/cancelled/needs_review or request error, 3 on timeout.
+A timeout leaves accepted work running. Continue with the same ID. Free.`,
+    cancel: `cancel <id>
+Request cancellation of unstarted work. Already incurred provider costs may be charged.
+Requires execution ownership or project ADMIN access.`,
+    "artifact-url": `artifact-url <execution-id> <artifact-id>
+Get a private output's temporary download URL, valid for up to 5 minutes.
+Treat it as private access; never send the developer API key to the storage host.`,
+    download: `download <execution-id> <artifact-id> --out <file>
+Save a private artifact after verifying size and SHA-256. Never overwrite an existing file.
+The developer API key is sent only to the Platform API, not the storage host.`,
+};
+export function commandHelp(name) {
+    return Object.hasOwn(commands, name) ? `Usage: noimos-platform ${commands[name]}\n` : undefined;
+}

package/dist/cli/download.js

@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+import { link, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { platformArtifactSchema } from "../client/index.js";
+function artifacts(output) {
+    if (!output)
+        return [];
+    const candidates = Array.isArray(output.artifacts) ? output.artifacts : [];
+    const found = [];
+    for (const candidate of candidates) {
+        const parsed = platformArtifactSchema.safeParse(candidate);
+        if (parsed.success)
+            found.push(parsed.data);
+    }
+    if (Array.isArray(output.results))
+        for (const result of output.results) {
+            if (result && typeof result === "object" && !Array.isArray(result) && result.data && typeof result.data === "object" && !Array.isArray(result.data)) {
+                found.push(...artifacts(result.data));
+            }
+        }
+    return found;
+}
+export async function downloadArtifact(client, id, artifactId, filename, transport = fetch) {
+    const execution = (await client.execution(id)).data;
+    const artifact = artifacts(execution.output).find((entry) => entry.id === artifactId);
+    if (!artifact)
+        throw new Error("Artifact is not present in this execution. Inspect execution output for available artifact IDs.");
+    const { data } = await client.artifactDownload(id, artifactId);
+    const url = new URL(data.url);
+    if (url.hostname !== "storage.googleapis.com" && !url.hostname.endsWith(".storage.googleapis.com"))
+        throw new Error("Unsupported artifact download host.");
+    const response = await transport(url, { method: "GET", redirect: "error", signal: AbortSignal.timeout(60000) }).catch(() => {
+        throw new Error("Artifact download failed. Retrieve a fresh URL and try again.");
+    });
+    if (!response.ok || !response.body)
+        throw new Error("Artifact download failed. Retrieve a fresh URL and try again.");
+    const reader = response.body.getReader(), chunks = [];
+    let bytes = 0;
+    try {
+        for (;;) {
+            const part = await reader.read();
+            if (part.done)
+                break;
+            bytes += part.value.byteLength;
+            if (bytes > artifact.sizeBytes) {
+                await reader.cancel();
+                throw new Error("Artifact exceeded its recorded size.");
+            }
+            chunks.push(part.value);
+        }
+    }
+    catch {
+        throw new Error("Artifact download failed. Retrieve a fresh URL and try again.");
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const buffer = Buffer.concat(chunks);
+    if (bytes !== artifact.sizeBytes || createHash("sha256").update(buffer).digest("hex") !== artifact.sha256)
+        throw new Error("Artifact integrity check failed; no file was saved.");
+    const path = resolve(filename);
+    const temporary = await mkdtemp(join(dirname(path), ".noimos-platform-"));
+    try {
+        const staged = join(temporary, "artifact");
+        await writeFile(staged, buffer, { flag: "wx", mode: 0o600 });
+        await link(staged, path);
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+    return { id, artifactId, path, sizeBytes: bytes, sha256: artifact.sha256 };
+}

package/dist/cli/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCli } from "./cli.js";
+process.exitCode = await runCli(process.argv.slice(2), process.env, console.log, console.error);

package/dist/client/index.js

@@ -0,0 +1,225 @@
+import { z } from "zod";
+import { platformInputFileSchema, platformInputUploadSchema, PLATFORM_UPLOAD_MAX_BYTES } from "../schema/platformPublicExecution.js";
+export { platformInputFileSchema, platformInputMimeSchema, PLATFORM_INPUT_MAX_BYTES } from "../schema/platformPublicExecution.js";
+import { PLATFORM_EXECUTION_RESPONSE_MAX_BYTES, platformCatalogSchema, platformQuoteSchema, platformExecutionSchema, platformCreateExecutionSchema, platformToolInputSchema, platformToolNameSchema, platformArtifactIdSchema, platformArtifactDownloadSchema, platformExecutionListQuerySchema, platformExecutionListSchema } from "../schema/platformPublicExecution.js";
+export { platformCreateExecutionSchema, platformToolInputSchema, platformExecutionSchema, platformArtifactIdSchema, platformArtifactSchema, platformExecutionListQuerySchema } from "../schema/platformPublicExecution.js";
+export const projectResultSchema = z.object({ data: z.object({ developerOrganizationId: z.string(), developerProjectId: z.string(), name: z.string() }), requestId: z.string() });
+export const usageResultSchema = z.object({ data: z.object({ month: z.string(), requests: z.number().int().nonnegative(), amountCents: z.number().nonnegative(), currency: z.literal("usd") }), requestId: z.string() });
+export const executionResultSchema = z.object({ data: platformExecutionSchema });
+const catalogResultSchema = z.object({ data: platformCatalogSchema });
+export const platformToolDiscoverySchema = z.object({
+    query: z.string().trim().min(1).max(200).optional().describe("Case-insensitive substring of a tool's name or description."),
+    category: platformCatalogSchema.shape.tools.element.shape.category.optional(),
+    availableOnly: z.boolean().optional().describe("Only tools with a configured provider; check executionEnabled separately."),
+    summary: z.boolean().optional().describe("Omit input schemas and examples; inspect a selected tool for those details."),
+}).strict();
+const quoteResultSchema = z.object({ data: platformQuoteSchema });
+const executionIdSchema = z.string().regex(/^[A-Za-z0-9_-]{1,128}$/);
+const idempotencySchema = z.string().regex(/^[A-Za-z0-9._:-]{8,128}$/);
+const publicErrors = {
+    platform_quote_changed: "The quote changed. Request a new quote before submitting another execution.",
+    platform_idempotency_key_used_for_another_request: "This idempotency key was already used for another request. Keep the original body to retrieve its result.",
+    platform_executions_disabled: "Paid executions are paused.",
+    platform_provider_not_configured: "This tool's provider is unavailable.",
+    platform_insufficient_balance_or_spending_limit_reached: "The prepaid balance or monthly spending limit is insufficient.",
+    platform_request_rate_exceeded: "The API key's request limit was reached. Wait before retrying.",
+    platform_api_key_scope_required: "The API key is missing the required scope.",
+    platform_artifact_unavailable: "This output file is unavailable or its retention period has ended.",
+};
+export class PlatformApiError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(`Platform API request failed (${status}). ${code && Object.hasOwn(publicErrors, code) ? publicErrors[code] : "Check the developer key, project access and limits in the console."}`);
+        this.status = status;
+        this.code = code;
+        this.name = "PlatformApiError";
+    }
+}
+async function responseJson(response) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error("The Platform API returned an empty response.");
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > PLATFORM_EXECUTION_RESPONSE_MAX_BYTES) {
+                await reader.cancel();
+                throw new Error("The Platform API response is too large.");
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.length;
+    }
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        throw new Error("The Platform API returned an invalid response.");
+    }
+}
+export function configFromEnvironment(env, source) {
+    if (!env.NOIMOS_PLATFORM_API_URL || !env.NOIMOS_PLATFORM_API_KEY)
+        throw new Error("Set NOIMOS_PLATFORM_API_URL and NOIMOS_PLATFORM_API_KEY from the developer console.");
+    return { apiUrl: env.NOIMOS_PLATFORM_API_URL, apiKey: env.NOIMOS_PLATFORM_API_KEY, source, local: env.NOIMOS_PLATFORM_ENV === "local" };
+}
+export class PlatformClient {
+    config;
+    transport;
+    baseUrl;
+    constructor(config, transport = fetch) {
+        this.config = config;
+        this.transport = transport;
+        const url = new URL(config.apiUrl);
+        if (url.username || url.password || url.search || url.hash || (url.protocol !== "https:" && !(config.local && url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname))))
+            throw new Error("The Platform API URL must use HTTPS. Explicit local mode permits loopback HTTP.");
+        if (!/^nmp_[A-Za-z0-9_-]{43}$/.test(config.apiKey))
+            throw new Error("A dedicated nmp_ developer API key is required.");
+        this.baseUrl = url.href.replace(/\/$/, "");
+    }
+    async request(path, schema, options) {
+        const body = options?.body === undefined ? undefined : JSON.stringify(options.body);
+        if (body && new TextEncoder().encode(body).byteLength > (path === "/tools/upload" ? PLATFORM_UPLOAD_MAX_BYTES : 65536))
+            throw new Error(path === "/tools/upload" ? "The upload exceeds 12 MiB." : "The tool request exceeds 64 KiB.");
+        let response;
+        try {
+            options?.signal?.throwIfAborted();
+            const timeout = AbortSignal.timeout(20000);
+            response = await this.transport(`${this.baseUrl}${path}`, { method: options?.method ?? "GET", redirect: "error", signal: options?.signal ? AbortSignal.any([timeout, options.signal]) : timeout,
+                headers: { authorization: `Bearer ${this.config.apiKey}`, "x-noimos-client": this.config.source, "idempotency-key": options?.idempotencyKey ?? crypto.randomUUID(),
+                    ...(body === undefined ? {} : { "content-type": "application/json" }) }, ...(body === undefined ? {} : { body }) });
+        }
+        catch {
+            options?.signal?.throwIfAborted();
+            throw new Error("The Platform API could not be reached. If submitting an execution, retry with the same body and idempotency key.");
+        }
+        const payload = await responseJson(response).catch(() => {
+            options?.signal?.throwIfAborted();
+            if (!response.ok)
+                throw new PlatformApiError(response.status, null);
+            throw new Error("The Platform API returned an invalid response. If submitting an execution, retain the same body and idempotency key.");
+        });
+        if (!response.ok) {
+            const parsed = z.object({ error: z.object({ message: z.string() }) }).safeParse(payload);
+            const code = parsed.success && Object.hasOwn(publicErrors, parsed.data.error.message) ? parsed.data.error.message : null;
+            throw new PlatformApiError(response.status, code);
+        }
+        const parsed = schema.safeParse(payload);
+        if (!parsed.success)
+            throw new Error("The Platform API returned an unexpected response. If submitting an execution, retain the same body and idempotency key.");
+        return parsed.data;
+    }
+    project() { return this.request("/tools/project", projectResultSchema); }
+    usage() { return this.request("/tools/usage", usageResultSchema); }
+    tools() { return this.request("/tools", catalogResultSchema); }
+    uploadInput(input) {
+        return this.request("/tools/upload", z.object({ data: platformInputFileSchema }), { method: "POST", body: platformInputUploadSchema.parse(input) });
+    }
+    async discoverTools(options = {}) {
+        const { query, category, availableOnly, summary } = platformToolDiscoverySchema.parse(options);
+        const { data } = await this.tools();
+        const search = query?.toLowerCase();
+        const tools = data.tools.filter((tool) => (!search || tool.name.toLowerCase().includes(search) || tool.description.toLowerCase().includes(search)) &&
+            (!category || tool.category === category) && (!availableOnly || tool.available));
+        return { data: { ...data, tools: summary ? tools.map(({ inputSchema, example, ...tool }) => tool) : tools } };
+    }
+    async tool(name) {
+        platformToolNameSchema.parse(name);
+        const { data } = await this.tools();
+        const tool = data.tools.find((entry) => entry.name === name);
+        if (!tool)
+            throw new Error("Tool is unavailable in the standalone Platform catalog. Run tools to discover supported operations.");
+        return { data: { ...tool, priceVersion: data.priceVersion, currency: data.currency, executionEnabled: data.executionEnabled } };
+    }
+    executions(input = {}) {
+        const parsed = platformExecutionListQuerySchema.parse(input);
+        const query = new URLSearchParams({ limit: String(parsed.limit) });
+        if (parsed.before)
+            query.set("before", parsed.before);
+        if (parsed.status)
+            query.set("status", parsed.status);
+        if (parsed.tool)
+            query.set("tool", parsed.tool);
+        return this.request(`/tools/executions?${query}`, z.object({ data: platformExecutionListSchema }));
+    }
+    quote(input) {
+        const parsed = platformToolInputSchema.safeParse(input);
+        if (!parsed.success)
+            throw new Error("Provide a tool name and a JSON object of arguments.");
+        return this.request("/tools/quote", quoteResultSchema, { method: "POST", body: parsed.data });
+    }
+    createExecution(input, idempotencyKey) {
+        const parsed = platformCreateExecutionSchema.safeParse(input);
+        if (!parsed.success)
+            throw new Error("Provide a tool, arguments, the quote's priceVersion and maximumChargeMicros.");
+        if (!idempotencySchema.safeParse(idempotencyKey).success)
+            throw new Error("Keep an idempotency key of 8–128 letters, digits, periods, underscores, colons or hyphens for this execution.");
+        return this.request(`/tools/${parsed.data.tool}`, executionResultSchema, { method: "POST", body: parsed.data, idempotencyKey });
+    }
+    execution(id, signal) {
+        if (!executionIdSchema.safeParse(id).success)
+            throw new Error("Provide a valid execution ID.");
+        return this.request(`/tools/executions/${id}`, executionResultSchema, { signal });
+    }
+    async waitExecution(id, timeoutMs = 20000, signal) {
+        executionIdSchema.parse(id);
+        if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 900000)
+            throw new Error("Wait must be between 1 and 900 seconds.");
+        const controller = new AbortController();
+        const timeout = new Error("Execution wait timed out; use the same execution ID to continue reading.");
+        const timer = setTimeout(() => controller.abort(timeout), timeoutMs);
+        const abort = () => controller.abort(signal?.reason);
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        let latest = null;
+        try {
+            for (;;) {
+                controller.signal.throwIfAborted();
+                latest = (await this.execution(id, controller.signal)).data;
+                if (!["queued", "running", "waiting"].includes(latest.status))
+                    return { data: latest, id, timedOut: false };
+                await new Promise((resolve, reject) => {
+                    const done = () => { controller.signal.removeEventListener("abort", cancelled); resolve(); };
+                    const pause = setTimeout(done, 5000);
+                    const cancelled = () => { clearTimeout(pause); controller.signal.removeEventListener("abort", cancelled); reject(controller.signal.reason); };
+                    controller.signal.addEventListener("abort", cancelled, { once: true });
+                    if (controller.signal.aborted)
+                        cancelled();
+                });
+            }
+        }
+        catch (error) {
+            if (error !== timeout)
+                throw error;
+            return { data: latest, id, timedOut: true };
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+        }
+    }
+    cancelExecution(id) {
+        if (!executionIdSchema.safeParse(id).success)
+            throw new Error("Provide a valid execution ID.");
+        return this.request(`/tools/executions/${id}/cancel`, executionResultSchema, { method: "POST" });
+    }
+    artifactDownload(id, artifactId) {
+        if (!executionIdSchema.safeParse(id).success || !platformArtifactIdSchema.safeParse(artifactId).success)
+            throw new Error("Provide valid execution and artifact IDs.");
+        return this.request(`/tools/executions/${id}/artifacts/${artifactId}/download`, z.object({ data: platformArtifactDownloadSchema }));
+    }
+}

package/dist/client/local-input.js

@@ -0,0 +1,37 @@
+import { open } from "node:fs/promises";
+import { constants } from "node:fs";
+import { extname } from "node:path";
+import { platformInputMimeSchema, PLATFORM_INPUT_MAX_BYTES } from "./index.js";
+const extensions = { ".mp3": "audio/mpeg", ".wav": "audio/wav", ".mp4": "video/mp4", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png" };
+export async function uploadLocalInput(client, path) {
+    const mimeType = platformInputMimeSchema.safeParse(extensions[extname(path).toLowerCase()]);
+    if (!mimeType.success)
+        throw new Error("Supported input files: JPG, PNG, WAV, MP3, MP4.");
+    let data;
+    try {
+        const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile() || stat.size < 1 || stat.size > PLATFORM_INPUT_MAX_BYTES)
+                throw new Error("Invalid file");
+            const buffer = Buffer.alloc(stat.size + 1);
+            let offset = 0;
+            while (offset < buffer.length) {
+                const { bytesRead } = await file.read(buffer, offset, buffer.length - offset, null);
+                if (!bytesRead)
+                    break;
+                offset += bytesRead;
+            }
+            if (offset !== stat.size)
+                throw new Error("File changed");
+            data = buffer.subarray(0, offset).toString("base64");
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch {
+        throw new Error("Input must be an existing regular file, at most 12 MiB. Symlinks are not accepted.");
+    }
+    return client.uploadInput({ mimeType: mimeType.data, data });
+}

package/dist/schema/platformPublicExecution.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+export const PLATFORM_EXECUTION_MAX_STEPS = 20;
+export const PLATFORM_STEP_OUTPUT_MAX_BYTES = 1_048_576;
+export const PLATFORM_EXECUTION_RESPONSE_MAX_BYTES = PLATFORM_EXECUTION_MAX_STEPS * PLATFORM_STEP_OUTPUT_MAX_BYTES + 65_536;
+export const platformJsonObjectSchema = z.record(z.string(), z.json());
+export const PLATFORM_INPUT_MAX_BYTES = 12 * 1024 * 1024;
+export const PLATFORM_UPLOAD_MAX_BYTES = 16 * 1024 * 1024 + 4096;
+export const platformInputFileIdSchema = z.string().regex(/^f_[a-f0-9]{64}$/);
+export const platformInputMimeSchema = z.enum(["image/jpeg", "image/png", "audio/wav", "audio/mpeg", "video/mp4"]);
+export const platformInputUploadSchema = z.object({ mimeType: platformInputMimeSchema, data: z.string().min(4).max(16 * 1024 * 1024) }).strict();
+export const platformInputFileSchema = z.object({ id: platformInputFileIdSchema, mimeType: platformInputMimeSchema,
+    sizeBytes: z.number().int().positive().max(PLATFORM_INPUT_MAX_BYTES), sha256: z.string().regex(/^[a-f0-9]{64}$/), expiresAt: z.iso.datetime() });
+export const platformMicrosSchema = z.number().int().min(0).max(1_000_000_000_000);
+export const platformToolNameSchema = z.string().regex(/^[a-z][a-z0-9_]{1,63}$/);
+export const platformExecutionStatusSchema = z.enum(["queued", "running", "waiting", "succeeded", "failed", "cancelled", "needs_review"]);
+const workspaceArgumentNames = new Set(["workspaceid", "workspaceids", "teamid", "provideraccountid", "provideraccountids", "datasetid", "datasetids", "knowledgebaseid", "sessionid", "skillid"]);
+const standaloneArgumentsSchema = platformJsonObjectSchema.superRefine((value, context) => {
+    for (const key of Object.keys(value))
+        if (workspaceArgumentNames.has(key.replaceAll("_", "").toLowerCase())) {
+            context.addIssue({ code: "custom", path: [key], message: "Workspace-owned data is unavailable on the standalone Platform." });
+        }
+}).describe("Self-contained tool arguments: prompts, public URLs or public account identifiers. Web workspace identifiers are not supported.");
+export const platformToolInputSchema = z.object({ tool: platformToolNameSchema.describe("Tool name from the standalone Platform catalog."), arguments: standaloneArgumentsSchema }).strict();
+export const platformCreateExecutionSchema = platformToolInputSchema.extend({
+    maximumChargeMicros: platformMicrosSchema,
+    priceVersion: z.string().min(1).max(100),
+}).strict();
+export const platformQuoteSchema = z.object({
+    tool: platformToolNameSchema, priceVersion: z.string(), currency: z.literal("usd"),
+    minimumChargeMicros: platformMicrosSchema, maximumChargeMicros: platformMicrosSchema,
+    expiresAt: z.string(),
+});
+export const platformExecutionSchema = z.object({
+    id: z.string(), tool: platformToolNameSchema, status: platformExecutionStatusSchema, cancelRequested: z.boolean(),
+    priceVersion: z.string(), currency: z.literal("usd"), reservedMicros: platformMicrosSchema, chargedMicros: platformMicrosSchema,
+    output: platformJsonObjectSchema.nullable(), errorCode: z.string().nullable(),
+    createdAt: z.string(), updatedAt: z.string(), completedAt: z.string().nullable(),
+});
+export const platformExecutionListQuerySchema = z.object({
+    limit: z.number().int().min(1).max(100).default(20).describe("Page size, 1–100."),
+    before: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/).optional().describe("nextBefore from the previous page."),
+    status: platformExecutionStatusSchema.optional().describe("Only executions with this status."),
+    tool: platformToolNameSchema.optional().describe("Only executions of this catalog tool."),
+}).strict();
+export const platformExecutionSummarySchema = platformExecutionSchema.omit({ output: true });
+export const platformExecutionListSchema = z.object({
+    executions: z.array(platformExecutionSummarySchema).max(100), nextBefore: z.string().nullable(),
+});
+export const platformArtifactIdSchema = z.string().regex(/^a_[A-Za-z0-9_-]{1,100}$/);
+export const platformArtifactSchema = z.object({
+    id: platformArtifactIdSchema, mimeType: z.enum(["image/jpeg", "image/png", "audio/wav", "audio/mpeg", "video/mp4"]),
+    sizeBytes: z.number().int().positive().max(64 * 1024 * 1024), sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    generation: z.string().regex(/^\d{1,30}$/), expiresAt: z.iso.datetime(),
+});
+export const platformArtifactDownloadSchema = z.object({ url: z.url().refine((value) => { const url = new URL(value); return url.protocol === "https:" && !url.username && !url.password; }), expiresAt: z.iso.datetime() });
+export const platformCatalogSchema = z.object({
+    priceVersion: z.string(), currency: z.literal("usd"), executionEnabled: z.boolean(),
+    tools: z.array(z.object({
+        name: platformToolNameSchema, description: z.string(), category: z.enum(["research", "seo", "social", "generation"]),
+        available: z.boolean(), inputSchema: platformJsonObjectSchema, example: platformJsonObjectSchema,
+        models: z.array(z.object({ id: z.string(), available: z.boolean(), example: platformJsonObjectSchema, priceDescription: z.string() })).optional(),
+        price: z.object({ minimumChargeMicros: platformMicrosSchema, unit: z.string(), unitPriceMicros: platformMicrosSchema.nullable(), description: z.string() }),
+    })),
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@noimosai/platform-cli",
+  "version": "0.1.0",
+  "description": "NoimosAI Developer Platform CLI for research, SEO, social data and media generation.",
+  "type": "module",
+  "bin": {
+    "noimos-platform": "./bin/noimos-platform.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "USAGE.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "homepage": "https://platform.noimosai.com",
+  "author": "AGOS Labs",
+  "license": "MIT",
+  "keywords": [
+    "noimosai",
+    "cli",
+    "mcp",
+    "marketing",
+    "seo",
+    "ai-agents"
+  ],
+  "dependencies": {
+    "zod": "^4.5.4"
+  }
+}