@meshy-ai/cli 0.1.0

package/dist/internal/device.js

@@ -0,0 +1,374 @@
+/**
+ * OAuth 2.0 Device Authorization Grant (RFC 8628) helpers.
+ *
+ * Implements:
+ *   - deviceAuthorization(): POST /oauth/device_authorization
+ *   - pollDeviceToken(): polling loop for /oauth/token with device_code grant
+ *   - ensureRequestedScopesGranted(): scope verification
+ */
+import { HintedError } from "./errors.js";
+import { USER_AGENT } from "./user-agent.js";
+// ---------------------------------------------------------------------------
+// Error classes
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when the /oauth/device_authorization endpoint returns 404.
+ * Indicates the meshyd deployment does not support device flow yet.
+ */
+export class DeviceFlowNotSupportedError extends HintedError {
+    constructor() {
+        super({
+            // Do NOT suggest --manual here: a meshyd old enough to lack
+            // device_authorization also lacks the OOB display branch that --manual
+            // depends on, so that flag would fail too. Only safe options are to
+            // wait for the backend deployment or use an API key.
+            message: "This Meshy API host does not support device login yet — retry after backend deployment or use an API key (meshy auth login --with-key).",
+            code: "device_flow_not_supported",
+            hint: "Run: meshy auth login --with-key msy_...",
+        });
+        this.name = "DeviceFlowNotSupportedError";
+    }
+}
+/**
+ * An error from the device token polling endpoint that carries the machine
+ * error code from the OAuth response body.
+ */
+export class DeviceFlowError extends HintedError {
+    oauthErrorCode;
+    constructor(params) {
+        super({ message: params.message, code: params.code, hint: params.hint });
+        this.name = "DeviceFlowError";
+        this.oauthErrorCode = params.oauthErrorCode;
+    }
+}
+// ---------------------------------------------------------------------------
+// Device authorization request
+// ---------------------------------------------------------------------------
+const REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * POST /oauth/device_authorization to start a device flow.
+ *
+ * @throws DeviceFlowNotSupportedError on 404
+ * @throws HintedError on other non-200 responses
+ */
+export async function deviceAuthorization(baseUrlV1, scope) {
+    const url = `${baseUrlV1}/oauth/device_authorization`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+                "User-Agent": USER_AGENT,
+            },
+            body: JSON.stringify({
+                client_id: "meshy-cli",
+                ...(scope ? { scope } : {}),
+            }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        throw new HintedError({
+            message: `Network error contacting device authorization endpoint: ${err instanceof Error ? err.message : String(err)}`,
+            code: "oauth_network",
+            hint: "Run: meshy auth login --with-key msy_...",
+        });
+    }
+    if (res.status === 404) {
+        throw new DeviceFlowNotSupportedError();
+    }
+    let parsed;
+    try {
+        parsed = await res.json();
+    }
+    catch {
+        throw new HintedError({
+            message: `Device authorization endpoint returned non-JSON (status ${res.status})`,
+            code: "oauth_bad_response",
+            hint: "Run: meshy auth login",
+        });
+    }
+    if (!res.ok) {
+        const obj = parsed;
+        const msg = (typeof obj["error_description"] === "string" ? obj["error_description"] : undefined) ??
+            (typeof obj["message"] === "string" ? obj["message"] : undefined) ??
+            (typeof obj["error"] === "string" ? obj["error"] : undefined) ??
+            `Device authorization endpoint error (status ${res.status})`;
+        throw new HintedError({
+            message: msg,
+            code: "oauth_device_error",
+            hint: "Run: meshy auth login",
+        });
+    }
+    const obj = parsed;
+    // Validate required fields.
+    if (typeof obj["device_code"] !== "string" || !obj["device_code"]) {
+        throw new HintedError({
+            message: "Device authorization response missing device_code",
+            code: "oauth_bad_response",
+            hint: "Run: meshy auth login",
+        });
+    }
+    if (typeof obj["user_code"] !== "string" || !obj["user_code"]) {
+        throw new HintedError({
+            message: "Device authorization response missing user_code",
+            code: "oauth_bad_response",
+            hint: "Run: meshy auth login",
+        });
+    }
+    if (typeof obj["verification_uri"] !== "string" || !obj["verification_uri"]) {
+        throw new HintedError({
+            message: "Device authorization response missing verification_uri",
+            code: "oauth_bad_response",
+            hint: "Run: meshy auth login",
+        });
+    }
+    const rawInterval = typeof obj["interval"] === "number" ? obj["interval"] : 5;
+    const interval = rawInterval < 1 ? 5 : rawInterval;
+    const expiresIn = typeof obj["expires_in"] === "number" && obj["expires_in"] > 0 ? obj["expires_in"] : 600;
+    return {
+        device_code: obj["device_code"],
+        user_code: obj["user_code"],
+        verification_uri: obj["verification_uri"],
+        verification_uri_complete: typeof obj["verification_uri_complete"] === "string"
+            ? obj["verification_uri_complete"]
+            : obj["verification_uri"],
+        expires_in: expiresIn,
+        interval,
+    };
+}
+// ---------------------------------------------------------------------------
+// Device token polling
+// ---------------------------------------------------------------------------
+/** Sleep for `ms` milliseconds. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * POST /oauth/token with grant_type=device_code once and return the result.
+ * Returns the parsed body (success or error) and the HTTP status.
+ */
+async function deviceTokenOnce(baseUrlV1, deviceCode) {
+    const url = `${baseUrlV1}/oauth/token`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+                "User-Agent": USER_AGENT,
+            },
+            body: JSON.stringify({
+                grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                device_code: deviceCode,
+                client_id: "meshy-cli",
+            }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        throw new HintedError({
+            message: `Network error polling device token: ${err instanceof Error ? err.message : String(err)}`,
+            code: "oauth_network",
+            hint: "Run: meshy auth login",
+        });
+    }
+    let body;
+    try {
+        body = (await res.json());
+    }
+    catch {
+        throw new HintedError({
+            message: `Device token endpoint returned non-JSON (status ${res.status})`,
+            code: "oauth_bad_response",
+            hint: "Run: meshy auth login",
+        });
+    }
+    return { status: res.status, body };
+}
+/** Validate and extract a TokenResponse from a successful device token body. */
+function extractTokenResponse(body) {
+    if (typeof body["access_token"] !== "string" || !body["access_token"]) {
+        throw new HintedError({
+            message: "Device token response missing access_token",
+            code: "oauth_bad_response",
+            hint: "Run: meshy auth login",
+        });
+    }
+    if (typeof body["token_type"] !== "string" ||
+        body["token_type"].toLowerCase() !== "bearer") {
+        throw new HintedError({
+            message: `Device token response has unexpected token_type: ${JSON.stringify(body["token_type"])}`,
+            code: "oauth_bad_response",
+            hint: "Run: meshy auth login",
+        });
+    }
+    const expiresIn = body["expires_in"];
+    if (typeof expiresIn !== "number" || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+        throw new HintedError({
+            message: `Device token response has invalid expires_in: ${JSON.stringify(expiresIn)}`,
+            code: "oauth_bad_response",
+            hint: "Run: meshy auth login",
+        });
+    }
+    if (typeof body["refresh_token"] !== "string" || !body["refresh_token"]) {
+        throw new HintedError({
+            message: "Device token response missing refresh_token",
+            code: "oauth_bad_response",
+            hint: "Run: meshy auth login",
+        });
+    }
+    return {
+        access_token: body["access_token"],
+        token_type: body["token_type"],
+        expires_in: expiresIn,
+        refresh_token: body["refresh_token"],
+        scope: typeof body["scope"] === "string" ? body["scope"] : undefined,
+        user_id: typeof body["user_id"] === "string" ? body["user_id"] : undefined,
+    };
+}
+const MAX_INTERVAL_S = 60;
+/**
+ * Poll the device token endpoint until the user approves, denies, or the
+ * token expires.
+ *
+ * Implements RFC 8628 §3.5 polling semantics:
+ *   - authorization_pending → wait current interval
+ *   - slow_down or HTTP 429 → interval += 5s (capped at 60s), wait
+ *   - expired_token or deadline exceeded → throw oauth_timeout
+ *   - access_denied → throw AUTH error
+ *   - invalid_grant → throw AUTH error (already consumed)
+ *   - 5xx / network → retry up to 3 consecutive, then throw
+ */
+export async function pollDeviceToken(baseUrlV1, deviceCode, opts) {
+    const deadline = opts.deadline ?? Date.now() + opts.expiresIn * 1000;
+    let intervalMs = (opts.interval < 1 ? 5 : opts.interval) * 1000;
+    /** Consecutive network-level errors (thrown by deviceTokenOnce). */
+    let consecutiveNetworkErrors = 0;
+    /** Consecutive 5xx HTTP errors. */
+    let consecutive5xxErrors = 0;
+    for (;;) {
+        if (Date.now() >= deadline) {
+            throw new HintedError({
+                message: "Device flow timed out waiting for authorization. Run: meshy auth login",
+                code: "oauth_timeout",
+                hint: "Run: meshy auth login",
+            });
+        }
+        let result;
+        try {
+            result = await deviceTokenOnce(baseUrlV1, deviceCode);
+            consecutiveNetworkErrors = 0;
+        }
+        catch (err) {
+            consecutiveNetworkErrors++;
+            if (consecutiveNetworkErrors >= 3) {
+                throw err;
+            }
+            await sleep(intervalMs);
+            continue;
+        }
+        const { status, body } = result;
+        // Success.
+        if (status === 200) {
+            consecutive5xxErrors = 0;
+            return extractTokenResponse(body);
+        }
+        // Parse the OAuth error code from the body.
+        const oauthError = typeof body["error"] === "string" ? body["error"] : undefined;
+        const humanMsg = (typeof body["error_description"] === "string" ? body["error_description"] : undefined) ??
+            (typeof body["message"] === "string" ? body["message"] : undefined) ??
+            oauthError ??
+            `Device token error (status ${status})`;
+        // Handle specific OAuth error codes.
+        if (oauthError === "authorization_pending") {
+            consecutive5xxErrors = 0;
+            opts.onPending?.();
+            await sleep(intervalMs);
+            continue;
+        }
+        if (oauthError === "slow_down" || status === 429) {
+            consecutive5xxErrors = 0;
+            intervalMs = Math.min(intervalMs + 5000, MAX_INTERVAL_S * 1000);
+            await sleep(intervalMs);
+            continue;
+        }
+        if (oauthError === "expired_token") {
+            // Use DeviceFlowError so oauthErrorCode:"expired_token" survives to
+            // --json output, letting machine consumers distinguish this from
+            // access_denied / invalid_grant. Exit code stays TIMED_OUT (the
+            // "oauth_timeout" code maps there in exitCodeFor).
+            throw new DeviceFlowError({
+                message: "Device flow authorization code expired. Run: meshy auth login",
+                code: "oauth_timeout",
+                oauthErrorCode: "expired_token",
+                hint: "Run: meshy auth login",
+            });
+        }
+        if (oauthError === "access_denied") {
+            throw new DeviceFlowError({
+                message: "Device login was denied by the user.",
+                code: "oauth_access_denied",
+                oauthErrorCode: "access_denied",
+                hint: "Run: meshy auth login",
+            });
+        }
+        if (oauthError === "invalid_grant") {
+            throw new DeviceFlowError({
+                message: "Device flow already consumed or invalid; restart login.",
+                code: "oauth_invalid_grant",
+                oauthErrorCode: "invalid_grant",
+                hint: "Run: meshy auth login",
+            });
+        }
+        // 5xx errors: retry up to 3 consecutive, then surface.
+        if (status >= 500) {
+            consecutive5xxErrors++;
+            if (consecutive5xxErrors >= 3) {
+                throw new HintedError({
+                    message: `Device token server error (status ${status}): ${humanMsg}`,
+                    code: "oauth_server_error",
+                    hint: "Run: meshy auth login",
+                });
+            }
+            await sleep(intervalMs);
+            continue;
+        }
+        // Other 400-level errors.
+        throw new HintedError({
+            message: humanMsg,
+            code: "oauth_device_error",
+            hint: "Run: meshy auth login",
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Scope verification
+// ---------------------------------------------------------------------------
+/**
+ * Verify that all requested scopes were granted.
+ *
+ * Both `requested` and `granted` are space-separated scope strings.
+ * Today both are "" — this trivially passes. Implemented generically for
+ * future use.
+ *
+ * @throws HintedError listing missing scopes if any requested scope is absent.
+ */
+export function ensureRequestedScopesGranted(requested, granted) {
+    const requestedScopes = requested.split(/\s+/).filter(Boolean);
+    if (requestedScopes.length === 0)
+        return;
+    const grantedScopes = new Set((granted ?? "").split(/\s+/).filter(Boolean));
+    const missing = requestedScopes.filter((s) => !grantedScopes.has(s));
+    if (missing.length > 0) {
+        throw new HintedError({
+            message: `The following requested scopes were not granted: ${missing.join(", ")}`,
+            code: "oauth_scope_denied",
+            hint: "Run: meshy auth login",
+        });
+    }
+}
+//# sourceMappingURL=device.js.map

package/dist/internal/device.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.js","sourceRoot":"","sources":["../../src/internal/device.ts"],"names":[],"mappings":"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"}

package/dist/internal/download.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Download a completed task's artifacts to the local filesystem.
+ *
+ * Two target shapes:
+ *   1. File path (e.g. `character/front.jpeg`) — used when the task has a
+ *      single downloadable artifact (most 2D image tasks). The Content-Type
+ *      of the HTTP response is authoritative; if the user-supplied extension
+ *      disagrees, the file is saved with the correct extension instead.
+ *   2. Directory path (anything without a recognized file extension) — used
+ *      when the task emits multiple artifacts (3D models, thumbnails,
+ *      textures, animation outputs). Each artifact is named after its role
+ *      (model.glb, thumbnail.png, texture_0_base_color.png, ...).
+ *
+ * A `meta.json` alongside the artifacts records the full task response plus
+ * the saved paths for later reference.
+ */
+import type { Task } from "../client/types.js";
+export interface Artifact {
+    /** Stable slot name ("model_glb", "image_0", "texture_0_base_color", ...) */
+    key: string;
+    /** Source URL (presigned). */
+    url: string;
+    /** Expected extension inferred from the slot name (no dot, may be empty). */
+    preferredExt: string;
+}
+export declare function enumerateArtifacts(task: Task): Artifact[];
+/** Heuristic: does this look like a file path (has an extension) or a dir? */
+export declare function looksLikeFile(path: string): boolean;
+export interface DownloadResult {
+    savedFiles: string[];
+    metadataPath: string;
+}
+export declare function downloadArtifacts(task: Task, outputPath: string, resource: string): Promise<DownloadResult>;
+//# sourceMappingURL=download.d.ts.map

package/dist/internal/download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../src/internal/download.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAO/C,MAAM,WAAW,QAAQ;IACvB,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,EAAE,CA4CzD;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,cAAc,CAAC,CA6DzB"}