@flixly/sdk 0.1.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -0,0 +1,227 @@
+// src/index.ts
+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;
+}
+export {
+  BASE_URL,
+  Flixly,
+  FlixlyError
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@flixly/sdk",
+  "version": "0.1.0",
+  "description": "Official Flixly AI SDK for Node.js and the browser. Generate images, video, audio, and chat completions through Flixly's public API.",
+  "keywords": [
+    "flixly",
+    "ai",
+    "image-generation",
+    "video-generation",
+    "chat",
+    "openai-compatible"
+  ],
+  "homepage": "https://github.com/Softforge-Digital/flixly-js-sdk#readme",
+  "bugs": "https://github.com/Softforge-Digital/flixly-js-sdk/issues",
+  "license": "MIT",
+  "author": "Flixly <support@flixly.ai>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Softforge-Digital/flixly-js-sdk.git"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "lint": "tsc --noEmit",
+    "test": "node --experimental-vm-modules --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "sideEffects": false
+}