@flixly/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flixly
+
+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

@@ -0,0 +1,126 @@
+# @flixly/sdk
+
+Official JavaScript / TypeScript SDK for the [Flixly](https://www.flixly.ai) AI API. Generate images, video, audio, and chat completions from one client.
+
+## Install
+
+```bash
+npm install @flixly/sdk
+```
+
+Requires Node.js 18+ (uses global `fetch`).
+
+## Quick start
+
+```ts
+import { Flixly } from "@flixly/sdk";
+
+const flixly = new Flixly({ apiKey: process.env.FLIXLY_API_KEY! });
+
+// Fast: image models return synchronously.
+const result = await flixly.generateAndWait({
+  model: "flux-dev",
+  prompt: "A cat wearing a top hat, oil painting style",
+  type: "TEXT_TO_IMAGE",
+  input: { aspect_ratio: "1:1", resolution: "1K" },
+});
+
+console.log(result.data.output_url); // cdn.flixly.ai URL
+```
+
+Get an API key at [www.flixly.ai/dashboard/settings/api-keys](https://www.flixly.ai/dashboard/settings/api-keys).
+
+## Webhooks (recommended for video / slow models)
+
+```ts
+await flixly.generate({
+  model: "veo-3-fast",
+  prompt: "Cinematic shot of mountains at dawn",
+  type: "TEXT_TO_VIDEO",
+  webhook_url: "https://example.com/flixly-webhook",
+});
+```
+
+Verify incoming webhook requests:
+
+```ts
+// In your webhook handler — Express, Hono, Next.js, etc.
+import { Flixly } from "@flixly/sdk";
+
+const valid = await Flixly.verifyWebhookSignature({
+  secret: process.env.FLIXLY_WEBHOOK_SECRET!,
+  timestamp: req.headers["x-flixly-timestamp"]!,
+  signature: req.headers["x-flixly-signature"]!,
+  body: rawBody, // pass the unmodified request body — JSON.parse + restringify will break verification
+});
+if (!valid) return res.status(401).end();
+```
+
+The webhook secret is shown once when you create the API key. Store it on your server like any other secret.
+
+## Rate limits
+
+Every response includes parsed rate-limit info — use it to pace yourself before a 429:
+
+```ts
+const res = await flixly.listModels();
+console.log(res.rateLimit);
+// { limit: 60, remaining: 42, resetAtSec: 1735056000 }
+```
+
+## Chat (OpenAI-compatible)
+
+```ts
+// Non-streaming
+const res = await flixly.chat({
+  model: "gpt-5-4-mini",
+  messages: [
+    { role: "user", content: "Explain async/await in one sentence." },
+  ],
+});
+console.log(res.data.choices[0].message.content);
+
+// Streaming
+for await (const chunk of flixly.chatStream({
+  model: "gpt-5-4-mini",
+  messages: [{ role: "user", content: "Write a haiku about TypeScript" }],
+})) {
+  process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "");
+}
+```
+
+## Errors
+
+API errors throw `FlixlyError` with the response code, status, and details:
+
+```ts
+import { Flixly, FlixlyError } from "@flixly/sdk";
+
+try {
+  await flixly.generate({ model: "flux-dev", prompt: "" });
+} catch (err) {
+  if (err instanceof FlixlyError) {
+    console.log(err.code, err.status, err.message);
+    // "invalid_request" 400 "prompt is required"
+  }
+}
+```
+
+## Configuration
+
+```ts
+new Flixly({
+  apiKey: "flx_live_...",
+  baseUrl: "https://www.flixly.ai", // default
+  timeoutMs: 120_000,               // default 2 minutes
+  fetch: customFetch,               // override (e.g. for proxies)
+});
+```
+
+## Spending caps & API key management
+
+Set a per-key monthly credit limit, configure default webhook URLs, and rotate webhook secrets at [/dashboard/settings/api-keys](https://www.flixly.ai/dashboard/settings/api-keys).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,254 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BASE_URL: () => BASE_URL,
+  Flixly: () => Flixly,
+  FlixlyError: () => FlixlyError
+});
+module.exports = __toCommonJS(index_exports);
+var BASE_URL = "https://www.flixly.ai";
+var FlixlyError = class extends Error {
+  constructor(args) {
+    super(args.message);
+    this.name = "FlixlyError";
+    this.status = args.status;
+    this.code = args.code;
+    this.details = args.details;
+    this.rateLimit = args.rateLimit;
+  }
+};
+var Flixly = class {
+  constructor(opts) {
+    if (!opts?.apiKey) throw new Error("Flixly: `apiKey` is required");
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl || BASE_URL).replace(/\/$/, "");
+    this.fetchImpl = opts.fetch || globalThis.fetch;
+    this.timeoutMs = opts.timeoutMs ?? 12e4;
+    if (!this.fetchImpl) {
+      throw new Error("Flixly: no fetch implementation. Pass `fetch` in options on Node < 18.");
+    }
+  }
+  // ─── Generations ───────────────────────────────────────────────
+  /** Submit a generation. Returns immediately with `processing` for async models, or `completed` for fast sync models. */
+  async generate(req) {
+    return this.request("POST", "/api/v1/generate", req);
+  }
+  /** Fetch the current state of a generation. */
+  async getGeneration(id) {
+    return this.request("GET", `/api/v1/generations/${encodeURIComponent(id)}`);
+  }
+  /**
+   * Submit a generation and poll until it completes or fails.
+   * Useful for short pipelines / one-shot scripts. Prefer
+   * `generate({ webhook_url })` in production.
+   */
+  async generateAndWait(req, opts = {}) {
+    const start = Date.now();
+    const interval = opts.pollIntervalMs ?? 2e3;
+    const maxWait = opts.maxWaitMs ?? 10 * 6e4;
+    const initial = await this.generate(req);
+    if (initial.data.status === "completed" || initial.data.status === "failed") {
+      return initial;
+    }
+    let last = initial;
+    while (Date.now() - start < maxWait) {
+      await sleep(interval);
+      last = await this.getGeneration(initial.data.id);
+      if (last.data.status === "completed" || last.data.status === "failed") {
+        return last;
+      }
+    }
+    throw new FlixlyError({
+      status: 408,
+      code: "timeout",
+      message: `Generation ${initial.data.id} did not finish within ${Math.round(maxWait / 1e3)}s. Last status: ${last.data.status}.`,
+      rateLimit: last.rateLimit
+    });
+  }
+  // ─── Models ────────────────────────────────────────────────────
+  /** List all available models. Includes per-model estimated_credits when authenticated. */
+  async listModels() {
+    return this.request("GET", "/api/v1/models");
+  }
+  // ─── Chat ──────────────────────────────────────────────────────
+  /** OpenAI-compatible chat completion (non-streaming). */
+  async chat(req) {
+    return this.request("POST", "/api/v1/chat/completions", { ...req, stream: false });
+  }
+  /**
+   * OpenAI-compatible streaming chat completion. Returns an async
+   * iterable of `chat.completion.chunk` events as parsed JSON. The
+   * stream terminates on `[DONE]`.
+   */
+  async *chatStream(req) {
+    const url = `${this.baseUrl}/api/v1/chat/completions`;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method: "POST",
+        headers: this.headers({ "Content-Type": "application/json" }),
+        body: JSON.stringify({ ...req, stream: true }),
+        signal: ac.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!res.ok) {
+      throw await responseToError(res);
+    }
+    if (!res.body) throw new Error("Flixly: streaming response has no body");
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      buf += decoder.decode(value, { stream: true });
+      const lines = buf.split("\n");
+      buf = lines.pop() || "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || !trimmed.startsWith("data:")) continue;
+        const payload = trimmed.slice(5).trim();
+        if (payload === "[DONE]") return;
+        try {
+          yield JSON.parse(payload);
+        } catch {
+        }
+      }
+    }
+  }
+  // ─── Account ───────────────────────────────────────────────────
+  /** Credit balance, plan, parallel + rate limits, and aggregate usage. */
+  async getAccount() {
+    return this.request("GET", "/api/v1/account");
+  }
+  // ─── Webhook signature verification (static) ───────────────────
+  /**
+   * Verify a Flixly webhook delivery. Returns true if and only if the
+   * signature is valid AND the timestamp is within `tolerance` seconds.
+   *
+   * Call this on EVERY webhook POST you receive — without it, anyone
+   * who guesses the URL can forge a delivery.
+   */
+  static async verifyWebhookSignature(args) {
+    if (!args.signature?.startsWith("sha256=")) return false;
+    const provided = args.signature.slice(7).toLowerCase();
+    const ts = Number(args.timestamp);
+    if (!Number.isFinite(ts)) return false;
+    const now = Math.floor(Date.now() / 1e3);
+    const tolerance = args.tolerance ?? 300;
+    if (Math.abs(now - ts) > tolerance) return false;
+    const bodyStr = typeof args.body === "string" ? args.body : new TextDecoder().decode(args.body);
+    const enc = new TextEncoder();
+    const key = await crypto.subtle.importKey(
+      "raw",
+      enc.encode(args.secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"]
+    );
+    const sigBuf = await crypto.subtle.sign("HMAC", key, enc.encode(`${args.timestamp}.${bodyStr}`));
+    const expectedHex = bufferToHex(sigBuf);
+    return timingSafeEqual(expectedHex, provided);
+  }
+  // ─── Internals ─────────────────────────────────────────────────
+  headers(extra = {}) {
+    return {
+      Authorization: `Bearer ${this.apiKey}`,
+      "User-Agent": "flixly-js/0.1.0",
+      ...extra
+    };
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method,
+        headers: this.headers(body ? { "Content-Type": "application/json" } : {}),
+        body: body ? JSON.stringify(body) : void 0,
+        signal: ac.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const rateLimit = parseRateLimit(res.headers);
+    if (!res.ok) {
+      throw await responseToError(res, rateLimit);
+    }
+    const data = await res.json();
+    return { data, rateLimit };
+  }
+};
+function parseRateLimit(h) {
+  const limit = Number(h.get("X-RateLimit-Limit"));
+  const remaining = Number(h.get("X-RateLimit-Remaining"));
+  const resetAtSec = Number(h.get("X-RateLimit-Reset"));
+  if (!Number.isFinite(limit) || !Number.isFinite(remaining) || !Number.isFinite(resetAtSec)) {
+    return null;
+  }
+  return { limit, remaining, resetAtSec };
+}
+async function responseToError(res, rateLimit) {
+  const rl = rateLimit ?? parseRateLimit(res.headers);
+  let code = "internal_error";
+  let message = `HTTP ${res.status}`;
+  let details;
+  try {
+    const body = await res.json();
+    if (body?.error) {
+      code = body.error.code || code;
+      message = body.error.message || message;
+      details = body.error.details;
+    }
+  } catch {
+  }
+  return new FlixlyError({ status: res.status, code, message, details, rateLimit: rl });
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function bufferToHex(buf) {
+  const bytes = new Uint8Array(buf);
+  let hex = "";
+  for (const b of bytes) hex += b.toString(16).padStart(2, "0");
+  return hex;
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BASE_URL,
+  Flixly,
+  FlixlyError
+});

package/dist/index.d.cts

@@ -0,0 +1,238 @@
+/**
+ * @flixly/sdk — Official SDK for the Flixly AI API.
+ *
+ * @example
+ * ```ts
+ * import { Flixly } from "@flixly/sdk";
+ *
+ * const flixly = new Flixly({ apiKey: process.env.FLIXLY_API_KEY! });
+ *
+ * // Quick: kick off a generation and wait for it.
+ * const result = await flixly.generateAndWait({
+ *   model: "flux-dev",
+ *   prompt: "A cat wearing a top hat, oil painting style",
+ *   type: "TEXT_TO_IMAGE",
+ *   input: { aspect_ratio: "1:1", resolution: "1K" },
+ * });
+ * console.log(result.output_url);
+ *
+ * // Or: subscribe via webhook (preferred for video / slow models).
+ * await flixly.generate({
+ *   model: "veo-3-fast",
+ *   prompt: "Cinematic shot of mountains at dawn",
+ *   webhook_url: "https://example.com/flixly-webhook",
+ * });
+ *
+ * // Verify incoming webhooks:
+ * const valid = await Flixly.verifyWebhookSignature({
+ *   secret: process.env.FLIXLY_WEBHOOK_SECRET!,
+ *   timestamp: req.headers["x-flixly-timestamp"]!,
+ *   signature: req.headers["x-flixly-signature"]!,
+ *   body: req.rawBody,
+ * });
+ * if (!valid) throw new Error("invalid signature");
+ * ```
+ */
+declare const BASE_URL = "https://www.flixly.ai";
+type TaskType = "TEXT_TO_IMAGE" | "IMAGE_TO_IMAGE" | "TEXT_TO_VIDEO" | "IMAGE_TO_VIDEO" | "VIDEO_TO_VIDEO" | "TEXT_TO_SPEECH" | "VOICE_CLONE" | "MUSIC_GENERATION" | "UPSCALE" | "REMOVE_BACKGROUND";
+type GenerationStatus = "pending" | "processing" | "completed" | "failed";
+interface GenerateInput {
+    aspect_ratio?: string;
+    resolution?: string;
+    duration?: string | number;
+    image_url?: string;
+    video_url?: string;
+    audio_url?: string;
+    [key: string]: unknown;
+}
+interface GenerateRequest {
+    /** Model id from `listModels()`. */
+    model: string;
+    /** Text prompt. */
+    prompt: string;
+    /** Task type. Inferred from the model when omitted. */
+    type?: TaskType;
+    /** Model-specific parameters (aspect ratio, resolution, image_url, etc.). */
+    input?: GenerateInput;
+    /**
+     * If set, we POST a signed event to this URL when the generation
+     * finishes. Overrides the key's default. Verify with
+     * `Flixly.verifyWebhookSignature()`.
+     */
+    webhook_url?: string;
+}
+interface Generation {
+    id: string;
+    status: GenerationStatus;
+    type: string;
+    model: string | null;
+    output_url: string | null;
+    status_url: string;
+    webhook_url?: string | null;
+    credits_charged: number;
+    error?: string | null;
+    created_at: string;
+    completed_at: string | null;
+    message?: string;
+}
+interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string | Array<{
+        type: string;
+        text?: string;
+        image_url?: {
+            url: string;
+        };
+    }>;
+}
+interface ChatRequest {
+    model: string;
+    messages: ChatMessage[];
+    stream?: boolean;
+    max_tokens?: number;
+    temperature?: number;
+}
+interface ChatResponse {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        message: {
+            role: string;
+            content: string;
+        };
+        finish_reason: string;
+    }>;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    credits_charged: number;
+}
+interface FlixlyModel {
+    id: string;
+    name: string;
+    type: string;
+    capabilities: string[];
+    estimated_credits?: number | null;
+    estimated_credits_per_1k_tokens?: number | null;
+}
+interface Account {
+    credits: {
+        subscription: number;
+        bonus: number;
+        total: number;
+    };
+    plan: {
+        name: string;
+        parallel_limit: number;
+        rate_limit: number;
+        renews_at: string | null;
+    };
+    usage: {
+        total_requests: number;
+        total_credits_used: number;
+        completed: number;
+        failed: number;
+        pending: number;
+    };
+}
+interface RateLimit {
+    /** Requests allowed per minute on this key's plan. */
+    limit: number;
+    /** Requests left in the current 60s window at the time of the response. */
+    remaining: number;
+    /** Unix epoch seconds when the window resets. */
+    resetAtSec: number;
+}
+/** A successful API response, with rate-limit headers parsed out. */
+interface FlixlyResponse<T> {
+    data: T;
+    rateLimit: RateLimit | null;
+}
+declare class FlixlyError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    readonly rateLimit: RateLimit | null;
+    constructor(args: {
+        status: number;
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+        rateLimit: RateLimit | null;
+    });
+}
+interface FlixlyOptions {
+    apiKey: string;
+    /** Override the API base URL (defaults to https://www.flixly.ai). */
+    baseUrl?: string;
+    /** Custom fetch implementation. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+    /** Per-request timeout in ms. Defaults to 120_000 (2 minutes). */
+    timeoutMs?: number;
+}
+declare class Flixly {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts: FlixlyOptions);
+    /** Submit a generation. Returns immediately with `processing` for async models, or `completed` for fast sync models. */
+    generate(req: GenerateRequest): Promise<FlixlyResponse<Generation>>;
+    /** Fetch the current state of a generation. */
+    getGeneration(id: string): Promise<FlixlyResponse<Generation>>;
+    /**
+     * Submit a generation and poll until it completes or fails.
+     * Useful for short pipelines / one-shot scripts. Prefer
+     * `generate({ webhook_url })` in production.
+     */
+    generateAndWait(req: GenerateRequest, opts?: {
+        pollIntervalMs?: number;
+        maxWaitMs?: number;
+    }): Promise<FlixlyResponse<Generation>>;
+    /** List all available models. Includes per-model estimated_credits when authenticated. */
+    listModels(): Promise<FlixlyResponse<{
+        models: FlixlyModel[];
+        total: number;
+    }>>;
+    /** OpenAI-compatible chat completion (non-streaming). */
+    chat(req: Omit<ChatRequest, "stream"> & {
+        stream?: false;
+    }): Promise<FlixlyResponse<ChatResponse>>;
+    /**
+     * OpenAI-compatible streaming chat completion. Returns an async
+     * iterable of `chat.completion.chunk` events as parsed JSON. The
+     * stream terminates on `[DONE]`.
+     */
+    chatStream(req: Omit<ChatRequest, "stream">): AsyncIterable<any>;
+    /** Credit balance, plan, parallel + rate limits, and aggregate usage. */
+    getAccount(): Promise<FlixlyResponse<Account>>;
+    /**
+     * Verify a Flixly webhook delivery. Returns true if and only if the
+     * signature is valid AND the timestamp is within `tolerance` seconds.
+     *
+     * Call this on EVERY webhook POST you receive — without it, anyone
+     * who guesses the URL can forge a delivery.
+     */
+    static verifyWebhookSignature(args: VerifyWebhookArgs): Promise<boolean>;
+    private headers;
+    private request;
+}
+interface VerifyWebhookArgs {
+    /** The HMAC secret you stored from your API key's webhook settings. */
+    secret: string;
+    /** The `X-Flixly-Timestamp` request header value (unix seconds, string). */
+    timestamp: string;
+    /** The `X-Flixly-Signature` request header value (`sha256=<hex>`). */
+    signature: string;
+    /** Raw request body bytes or string. MUST be unmodified — JSON.parse + re-stringify will break verification. */
+    body: string | Uint8Array;
+    /** Reject signatures older than this many seconds. Defaults to 300 (5 minutes) to prevent replays. */
+    tolerance?: number;
+}
+
+export { type Account, BASE_URL, type ChatMessage, type ChatRequest, type ChatResponse, Flixly, FlixlyError, type FlixlyModel, type FlixlyOptions, type FlixlyResponse, type GenerateInput, type GenerateRequest, type Generation, type GenerationStatus, type RateLimit, type TaskType, type VerifyWebhookArgs };