movoa-ai 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Movoa (https://movoa.ai)
+
+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/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# movoa
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Unlimited AI video generator with sound: on paid plans the tenth take of a shot costs what the first did, and your first clip is free to make right now. This is the official TypeScript / JavaScript SDK for [Movoa](https://movoa.ai/?utm_source=npm&utm_medium=package), for Node 18+, Deno and Bun: one API key turns a prompt into [text to video](https://movoa.ai/video/text-to-video), or a still into [photo to video](https://movoa.ai/video/photo-to-video), and every clip comes back as [AI video with audio](https://movoa.ai/video/ai-video-with-audio).
+
+```bash
+npm install movoa-ai
+# Deno / JSR
+deno add jsr:@movoa/movoa
+```
+
+```ts
+import { generateVideo } from "movoa-ai";
+
+const clip = await generateVideo("a paper boat drifting down a rain gutter, low angle, slow push-in");
+console.log(clip); // URL of the finished MP4, sound included
+```
+
+Uses the global `fetch`, no dependencies. `generateVideo` submits the run, waits for it and resolves to the URL of the finished file.
+
+## API key
+
+Sign in on [movoa.ai](https://movoa.ai/?utm_source=npm&utm_medium=package), create a key at [movoa.ai/settings/apikeys](https://movoa.ai/settings/apikeys), then pass it as `apiKey` or set it in the environment:
+
+```bash
+export MOVOA_API_KEY=sk-...
+```
+
+Runs cost credits on your Movoa account, at the prices on [movoa.ai/pricing](https://movoa.ai/pricing).
+
+```ts
+import { credits } from "movoa-ai";
+console.log(await credits()); // remaining credits on the account
+```
+
+## Text to video and photo to video
+
+```ts
+// text to video, vertical, 10 seconds
+await generateVideo("a fox trotting through fresh snow at dawn, tracking shot", { duration: 10, aspectRatio: "9:16" });
+
+// photo to video: the photo becomes the first frame
+await generateVideo("the camera slowly orbits the statue", { imageUrl: "https://example.com/statue.jpg" });
+
+// another model
+await generateVideo("a street drummer in the rain, close-up", { model: "seedance-2-5", duration: 10, resolution: "720p" });
+```
+
+| model | options |
+|---|---|
+| `minimax-h3` (default) | `duration` 4 / 5 / 6 / 8 / 10 / 15 · `resolution` 480p / 768p · `aspectRatio` 16:9 / 9:16 / 1:1 |
+| `veo-3-1-fast` | `duration` 8 · `resolution` 720p · `aspectRatio` 16:9 / 9:16 (photo to video: 16:9) |
+| `seedance-2-5` | `duration` 5 / 10 / 15 / 20 / 25 / 30 · `resolution` 480p / 720p · `aspectRatio` 16:9 / 9:16 / 1:1 |
+| `seedance-2`, `seedance-2-fast`, `seedance-2-mini` | `duration` 4 / 6 / 8 / 10 · `resolution` 480p / 720p · `aspectRatio` |
+
+Anything else goes in `options: { … }` and is sent as it is. Every run asks for sound. On the site: [Seedance 2.5](https://movoa.ai/video/seedance-2-5) and [Veo 3](https://movoa.ai/video/google-veo-3).
+
+## Submit now, collect later
+
+```ts
+import { submit, status, wait } from "movoa-ai";
+
+const id = await submit("a lighthouse in a storm, waves crashing", { duration: 6 });
+console.log((await status(id)).status); // pending | processing | success | failed | canceled
+const url = await wait(id);             // polls every 10 seconds, 30 minutes by default
+```
+
+While a run waits in line, `status()` returns `queued: true` and `queueEta` in seconds.
+
+## Errors worth catching
+
+Every failure is a `MovoaError` with a `kind`, and a subclass you can test with `instanceof`:
+
+- `AuthError` (`auth`): no key, or the key is wrong or deleted; create one at [movoa.ai/settings/apikeys](https://movoa.ai/settings/apikeys)
+- `QuotaError` (`quota`): the account does not have enough credits for this run
+- `PlanError` (`plan`): that model or quality needs a plan on the account
+- `BusyError` (`busy`): too many runs on this account are generating at once
+- `RejectedError` (`rejected`): the content filter refused the prompt, or a cooldown is active; reword it
+- `GenerationError` (`failed`): the run was accepted but failed or was canceled; `.errorMessage` says why
+- `TimeoutError` (`timeout`): the wait ran out; `.taskId` lets you check the run later with `status()`
+
+Any other refusal is a plain `MovoaError` (`other`) with the server's message.
+
+MIT licensed. Made by [Movoa](https://movoa.ai/?utm_source=npm&utm_medium=package).

package/dist/mod.d.ts

@@ -0,0 +1,122 @@
+/** The service this module talks to. */
+export declare const BASE_URL = "https://movoa.ai";
+/** Where users create API keys. */
+export declare const KEYS_URL: string;
+/** Model ids. `minimax-h3` is the default and the cheapest. */
+export declare const MODELS: readonly ["minimax-h3", "veo-3-1-fast", "seedance-2-5", "seedance-2", "seedance-2-fast", "seedance-2-mini"];
+export declare const DEFAULT_MODEL = "minimax-h3";
+/**
+ * What went wrong, so callers can decide what to do next.
+ * auth: no or bad key · quota: not enough credits · plan: model or quality needs a plan ·
+ * busy: too many runs at once · rejected: content filter or cooldown, reword ·
+ * failed: the run was accepted but failed or was canceled · timeout: still running, check later ·
+ * other: any other refusal, network failure or unexpected answer
+ */
+export type ErrorKind = "auth" | "quota" | "plan" | "busy" | "rejected" | "failed" | "timeout" | "other";
+/** Every failure is a MovoaError; branch on `kind` or on the subclass. */
+export declare class MovoaError extends Error {
+    readonly kind: ErrorKind;
+    /** HTTP status, when there was a response. */
+    status?: number;
+    /** Envelope code (0, -1, -2, -3). */
+    code?: number;
+    /** `data.reason` the service sent, if any. */
+    reason?: string;
+    /** The run this is about (failed and timeout). */
+    taskId?: string;
+    constructor(message: string, kind?: ErrorKind, extra?: {
+        status?: number;
+        code?: number;
+        reason?: string;
+        taskId?: string;
+    });
+}
+/** No API key, or the key is invalid or deleted. */
+export declare class AuthError extends MovoaError {
+    constructor(m: string, e?: {});
+}
+/** The account does not have enough credits for this run. */
+export declare class QuotaError extends MovoaError {
+    constructor(m: string, e?: {});
+}
+/** This model or quality needs a plan, or the account has never bought credits. */
+export declare class PlanError extends MovoaError {
+    constructor(m: string, e?: {});
+}
+/** Too many runs on this account are generating at once. */
+export declare class BusyError extends MovoaError {
+    constructor(m: string, e?: {});
+}
+/** The content filter refused the prompt (code -2) or a cooldown is active (code -3). Reword it. */
+export declare class RejectedError extends MovoaError {
+    constructor(m: string, e?: {});
+}
+/** The run was accepted but ended as failed or canceled. */
+export declare class GenerationError extends MovoaError {
+    readonly errorMessage?: string;
+    readonly failureKind?: string;
+    constructor(m: string, errorMessage?: string, failureKind?: string, taskId?: string);
+}
+/** The wait ran out; the run may still finish. `taskId` lets you check it later. */
+export declare class TimeoutError extends MovoaError {
+    constructor(m: string, taskId: string);
+}
+/** Connection options shared by every call. */
+export interface ClientOptions {
+    /** Defaults to the `MOVOA_API_KEY` environment variable. */
+    apiKey?: string;
+    /** Defaults to `MOVOA_BASE_URL`, then https://movoa.ai. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+/** Options for calls that wait for the result. */
+export interface WaitOptions extends ClientOptions {
+    /** Milliseconds. Default 30 minutes. */
+    timeout?: number;
+    /** Milliseconds between polls. Default 10 seconds. */
+    pollEvery?: number;
+}
+/** What to generate. Anything not listed is sent in `options` as it is. */
+export interface VideoOptions {
+    model?: string;
+    /** A public https image; turns the run into photo to video with it as the first frame. */
+    imageUrl?: string;
+    duration?: number;
+    resolution?: string;
+    aspectRatio?: string;
+    /** Extra model options, sent as they are. */
+    options?: Record<string, unknown>;
+}
+/** The run record returned by `status`. */
+export interface Task {
+    id: string;
+    status: "pending" | "processing" | "success" | "failed" | "canceled" | string;
+    videos?: string[];
+    errorMessage?: string;
+    failureKind?: string;
+    queued?: boolean;
+    /** Seconds. */
+    queueEta?: number;
+    [k: string]: unknown;
+}
+type Envelope = {
+    code?: number;
+    message?: string;
+    data?: any;
+};
+/**
+ * Map a refusal to the error that says what to do next. movoa.ai answers almost
+ * every refusal as HTTP 200 with a non-zero `code` and a `data.reason`.
+ */
+export declare function errorFor(status: number, body: Envelope): MovoaError;
+/** Start one run and resolve to its task id without waiting. */
+export declare function submit(prompt: string, v?: VideoOptions, o?: ClientOptions): Promise<string>;
+/** Fetch the run record: `status` is pending, processing, success, failed or canceled. */
+export declare function status(taskId: string, o?: ClientOptions): Promise<Task>;
+/** Poll a run until it finishes and resolve to the video URL. */
+export declare function wait(taskId: string, o?: WaitOptions): Promise<string>;
+/** Generate one clip with sound and resolve to its URL. */
+export declare function generateVideo(prompt: string, v?: VideoOptions & WaitOptions): Promise<string>;
+/** Resolve to the remaining credits on the account. */
+export declare function credits(o?: ClientOptions): Promise<number>;
+export {};

package/dist/mod.js

@@ -0,0 +1,193 @@
+// Official SDK for Movoa (movoa.ai), the AI video generator with sound. See README.md.
+/** The service this module talks to. */
+export const BASE_URL = "https://movoa.ai";
+/** Where users create API keys. */
+export const KEYS_URL = `${BASE_URL}/settings/apikeys`;
+/** Model ids. `minimax-h3` is the default and the cheapest. */
+export const MODELS = [
+    "minimax-h3", "veo-3-1-fast", "seedance-2-5", "seedance-2", "seedance-2-fast", "seedance-2-mini",
+];
+export const DEFAULT_MODEL = "minimax-h3";
+/** Every failure is a MovoaError; branch on `kind` or on the subclass. */
+export class MovoaError extends Error {
+    kind;
+    /** HTTP status, when there was a response. */
+    status;
+    /** Envelope code (0, -1, -2, -3). */
+    code;
+    /** `data.reason` the service sent, if any. */
+    reason;
+    /** The run this is about (failed and timeout). */
+    taskId;
+    constructor(message, kind = "other", extra = {}) {
+        super(message);
+        this.kind = kind;
+        this.name = "MovoaError";
+        Object.assign(this, extra);
+    }
+}
+/** No API key, or the key is invalid or deleted. */
+export class AuthError extends MovoaError {
+    constructor(m, e = {}) { super(m, "auth", e); this.name = "AuthError"; }
+}
+/** The account does not have enough credits for this run. */
+export class QuotaError extends MovoaError {
+    constructor(m, e = {}) { super(m, "quota", e); this.name = "QuotaError"; }
+}
+/** This model or quality needs a plan, or the account has never bought credits. */
+export class PlanError extends MovoaError {
+    constructor(m, e = {}) { super(m, "plan", e); this.name = "PlanError"; }
+}
+/** Too many runs on this account are generating at once. */
+export class BusyError extends MovoaError {
+    constructor(m, e = {}) { super(m, "busy", e); this.name = "BusyError"; }
+}
+/** The content filter refused the prompt (code -2) or a cooldown is active (code -3). Reword it. */
+export class RejectedError extends MovoaError {
+    constructor(m, e = {}) { super(m, "rejected", e); this.name = "RejectedError"; }
+}
+/** The run was accepted but ended as failed or canceled. */
+export class GenerationError extends MovoaError {
+    errorMessage;
+    failureKind;
+    constructor(m, errorMessage, failureKind, taskId) {
+        super(m, "failed", { taskId });
+        this.errorMessage = errorMessage;
+        this.failureKind = failureKind;
+        this.name = "GenerationError";
+    }
+}
+/** The wait ran out; the run may still finish. `taskId` lets you check it later. */
+export class TimeoutError extends MovoaError {
+    constructor(m, taskId) { super(m, "timeout", { taskId }); this.name = "TimeoutError"; }
+}
+function env(name) {
+    // deno-lint-ignore no-explicit-any
+    const g = globalThis;
+    try {
+        return g.process?.env?.[name] ?? g.Deno?.env?.get(name);
+    }
+    catch {
+        return undefined; // Deno without --allow-env
+    }
+}
+/**
+ * Map a refusal to the error that says what to do next. movoa.ai answers almost
+ * every refusal as HTTP 200 with a non-zero `code` and a `data.reason`.
+ */
+export function errorFor(status, body) {
+    const message = body.message || `request failed (HTTP ${status})`;
+    const reason = typeof body.data?.reason === "string" ? body.data.reason : undefined;
+    const extra = { status, code: body.code, reason };
+    if (status === 401)
+        return new AuthError(message.includes(KEYS_URL) ? message : `${message} (create a key at ${KEYS_URL})`, extra);
+    if (body.code === -2 || body.code === -3)
+        return new RejectedError(message, extra);
+    if (reason === "insufficient_credits")
+        return new QuotaError(message, extra);
+    if (reason === "plan_required")
+        return new PlanError(message, extra);
+    if (reason === "concurrency")
+        return new BusyError(message, extra);
+    if (/no auth/i.test(message))
+        return new AuthError(`${message}. Create a key at ${KEYS_URL}`, extra);
+    return new MovoaError(message, "other", extra);
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function post(path, body, o) {
+    const key = (o.apiKey || env("MOVOA_API_KEY") || "").trim();
+    if (!key)
+        throw new AuthError(`No API key: pass apiKey or set MOVOA_API_KEY. Create a key at ${KEYS_URL}`);
+    const base = (o.baseUrl || env("MOVOA_BASE_URL") || BASE_URL).replace(/\/$/, "");
+    let res;
+    try {
+        res = await (o.fetch ?? fetch)(base + path, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${key}` },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+    }
+    catch (e) {
+        throw new MovoaError(`Could not reach movoa.ai: ${e.message}`, "other");
+    }
+    const text = await res.text();
+    let json;
+    try {
+        json = text ? JSON.parse(text) : {};
+    }
+    catch {
+        json = undefined;
+    }
+    if (res.status === 401)
+        throw errorFor(401, json ?? {});
+    if (!json || typeof json !== "object")
+        throw new MovoaError(`movoa.ai returned a non-JSON response (HTTP ${res.status})`, "other", { status: res.status });
+    if (res.status < 400 && json.code === 0)
+        return json;
+    throw errorFor(res.status, json);
+}
+/** Start one run and resolve to its task id without waiting. */
+export async function submit(prompt, v = {}, o = {}) {
+    if (!prompt?.trim())
+        throw new TypeError("prompt is required");
+    const options = { sound: true };
+    for (const [k, val] of Object.entries(v.options ?? {}))
+        if (val !== undefined && val !== null)
+            options[k] = val;
+    if (v.duration !== undefined)
+        options.duration = v.duration;
+    if (v.resolution !== undefined)
+        options.resolution = v.resolution;
+    if (v.aspectRatio !== undefined)
+        options.aspect_ratio = v.aspectRatio;
+    if (v.imageUrl)
+        options.image_input = [v.imageUrl];
+    const json = await post("/api/ai/generate", {
+        // The server routes by model; this only has to be non-empty.
+        provider: "auto",
+        mediaType: "video",
+        model: v.model ?? DEFAULT_MODEL,
+        scene: v.imageUrl ? "image-to-video" : "text-to-video",
+        prompt,
+        options,
+    }, o);
+    const id = json.data?.id;
+    if (!id)
+        throw new MovoaError("movoa.ai accepted the run but returned no id", "other");
+    return String(id);
+}
+/** Fetch the run record: `status` is pending, processing, success, failed or canceled. */
+export async function status(taskId, o = {}) {
+    const json = await post("/api/ai/query", { taskId }, o);
+    return (json.data ?? {});
+}
+/** Poll a run until it finishes and resolve to the video URL. */
+export async function wait(taskId, o = {}) {
+    const timeout = o.timeout ?? 30 * 60_000;
+    const every = o.pollEvery ?? 10_000;
+    const deadline = Date.now() + timeout;
+    for (;;) {
+        const t = await status(taskId, o);
+        if (t.status === "success") {
+            if (!t.videos?.length)
+                throw new GenerationError(`run ${taskId} finished with no video`, undefined, undefined, taskId);
+            return String(t.videos[0]);
+        }
+        if (t.status === "failed" || t.status === "canceled") {
+            throw new GenerationError(`run ${taskId} ${t.status}${t.errorMessage ? `: ${t.errorMessage}` : ""}`, t.errorMessage, t.failureKind, taskId);
+        }
+        if (Date.now() + every > deadline) {
+            throw new TimeoutError(`run ${taskId} is still generating; check it later with status()`, taskId);
+        }
+        await sleep(every);
+    }
+}
+/** Generate one clip with sound and resolve to its URL. */
+export async function generateVideo(prompt, v = {}) {
+    return wait(await submit(prompt, v, v), v);
+}
+/** Resolve to the remaining credits on the account. */
+export async function credits(o = {}) {
+    const json = await post("/api/user/get-user-credits", undefined, o);
+    return Number(json.data?.remainingCredits ?? 0);
+}

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "movoa-ai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Unlimited AI video generator with sound: on paid plans the tenth take of a shot costs what the first did, and your first clip is free to make right now. Official TypeScript / JavaScript SDK for Movoa (movoa.ai): text to video and photo to video with sound from Node, Deno or Bun.",
+  "type": "module",
+  "main": "./dist/mod.js",
+  "types": "./dist/mod.d.ts",
+  "exports": { ".": { "types": "./dist/mod.d.ts", "default": "./dist/mod.js" } },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "keywords": ["ai", "video-generation", "ai-video-generator", "text-to-video", "image-to-video", "photo-to-video", "ai-video-with-audio", "minimax-h3", "seedance-2-5", "veo-3", "movoa"],
+  "homepage": "https://movoa.ai/?utm_source=npm&utm_medium=package",
+  "repository": { "type": "git", "url": "git+https://github.com/hanshs474/movoa-ts.git" },
+  "bugs": "https://github.com/hanshs474/movoa-ts/issues",
+  "license": "MIT",
+  "author": "Movoa (https://movoa.ai)",
+  "scripts": {
+    "build": "tsc mod.ts --outDir dist --declaration --target es2022 --module es2022 --moduleResolution bundler --lib es2022,dom --skipLibCheck",
+    "test": "npm run build && node --test test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": { "typescript": "^5.6.0" }
+}