Openinary Docs

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: openinary
      POSTGRES_USER: openinary
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql/data

  app:
    image: ghcr.io/yourorg/openinary:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://openinary:secret@postgres:5432/openinary
      UPLOAD_DIR: /data/uploads
      CACHE_DIR: /data/cache
      PUBLIC_URL: http://localhost:3000
      AUTH_ENABLED: "true"
      DASHBOARD_USERNAME: admin
      DASHBOARD_PASSWORD: change-me-in-production
      IMG_SIGNING_SECRET: change-me-in-production
    volumes:
      - uploads:/data/uploads
      - cache:/data/cache
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  pgdata:
  uploads:
  cache:

docker compose up -d
# Migrations run automatically on first startup
# Open http://localhost:3000 and sign in

# Create "thumbnail" preset
curl -X POST http://localhost:3000/api/transformations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"thumbnail","transform_string":"w_200,h_200,c_fill,f_webp,q_80"}'

# Use it in any image URL
GET /img/t_thumbnail/photos/portrait.jpg

# Submit a transcoding job
curl -X POST http://localhost:3000/api/asset/uuid-here/transcode \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"format":"webm","width":1280,"quality":28}'

# Poll status
curl http://localhost:3000/api/transcode-jobs/<job-id> \
  -H "Authorization: Bearer <token>"

# Approve an asset
curl -X PATCH http://localhost:3000/api/asset/uuid/moderation \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"status":"approved"}'

npm install openinary
# or
pnpm add openinary

import { OpeninaryClient } from "openinary";

const client = new OpeninaryClient({
  baseUrl: "http://localhost:3000",  // required
  apiKey:  "ok_yourkey",           // API key or…
  token:   "eyJhbGci...",            // …JWT token
});

const client = new OpeninaryClient({ baseUrl, apiKey });

// List assets
const assets = await client.assets.list({ folder: "marketing", limit: 50 });

// Upload a file (Node.js Buffer or browser File)
const asset = await client.assets.upload(file, {
  folder: "products",
  tags: ["hero", "2024"],
});

// Upload from URL
const asset = await client.assets.uploadFromUrl("https://example.com/img.jpg", {
  folder: "imports",
});

// Upload from base64
const asset = await client.assets.uploadFromBase64(
  "data:image/jpeg;base64,/9j/4AAQ...",
  { filename: "avatar.jpg", folder: "users" }
);

// Get single asset
const asset = await client.assets.get("550e8400-...");

// Update metadata
const updated = await client.assets.update("550e8400-...", {
  filename: "new-name.jpg",
  folder:   "archived",
  context:  { author: "Alice", campaign: "summer" },
});

// Delete (soft)
await client.assets.delete("550e8400-...");

// Restore from trash
await client.assets.restore("550e8400-...");

// Search
const results = await client.assets.search("mountains", { folder: "travel" });

// Add / remove tags
await client.assets.addTags("uuid", ["featured", "sale"]);
await client.assets.removeTags("uuid", ["sale"]);

// Bulk operations
await client.assets.bulkDelete(["uuid-1", "uuid-2"]);
await client.assets.bulkMove(["uuid-1", "uuid-2"], "archived");

// Build a URL with transform params
const url = client.assets.url(asset.file_key, {
  width:   400,
  height:  400,
  crop:    "fill",
  format:  "webp",
  quality: 80,
});
// → http://localhost:3000/img/w_400,h_400,c_fill,f_webp,q_80/photos/img.jpg

// All supported TransformOptions fields:
type TransformOptions = {
  width?:      number;           // w_
  height?:     number;           // h_
  crop?:       string;           // c_ (fill|fit|scale|thumb|pad|crop)
  gravity?:    string;           // g_ (center|face|north|south…)
  quality?:    number;           // q_
  format?:     string;           // f_ (webp|avif|jpeg|png|gif|mp4…)
  radius?:     string | number;  // r_ (px or "max" for circle)
  effect?:     string;           // e_ (grayscale|blur|sharpen…)
  background?: string;           // b_
  named?:      string;           // t_ (named preset)
  dpr?:        number;           // dpr_
  startOffset?: number;          // so_ (video trim start)
  endOffset?:   number;          // eo_ (video trim end)
  fps?:         number;          // fps_
  bitrate?:     string;          // br_
};

// Multi-stage transforms (chained with /)
const url = client.assets.buildTransformString([
  { width: 800, crop: "fill" },
  { effect: "grayscale", quality: 70 },
]);
// → w_800,c_fill/e_grayscale,q_70

// Get a signed URL (requires server call)
const { url, expires_at } = await client.assets.signedUrl("uuid", {
  transforms: "w_400,c_fill",
  expires: 3600,
});

// List webhooks
const hooks = await client.webhooks.list();

// Create
const hook = await client.webhooks.create({
  url:    "https://your-server.com/webhook",
  events: ["upload.complete", "transcode.complete"],
});
console.log(hook.secret); // ← store securely, shown once

// Toggle enabled
await client.webhooks.update(hook.id, { enabled: false });

// Delivery history
const deliveries = await client.webhooks.deliveries(hook.id);

// Delete
await client.webhooks.delete(hook.id);

// Users
const users   = await client.admin.users.list();
const updated = await client.admin.users.updateRole(userId, "editor");
await client.admin.users.delete(userId);

// API Keys
const keys    = await client.admin.apiKeys.list();
const created = await client.admin.apiKeys.create("CI pipeline");
console.log(created.key); // ← shown once
await client.admin.apiKeys.revoke(keyId);

// Named transformations
await client.admin.namedTransformations.create("avatar", "w_200,h_200,c_fill,r_max");
await client.admin.namedTransformations.delete("avatar");

// Upload presets
await client.admin.uploadPresets.create({
  name: "strict_images",
  allowed_formats: ["jpg","png","webp"],
  max_size: 5 * 1024 * 1024,
  unsigned: false,
});

// Analytics
const storage   = await client.admin.analytics.storage();
const bandwidth = await client.admin.analytics.bandwidth({ days: 7 });

// Helper to build transform strings in your own frontend
function buildTransformUrl(baseUrl: string, fileKey: string, transforms: string) {
  return `${baseUrl}/img/${transforms}/${fileKey}`;
}

// Progressive enhancement: serve WebP with JPEG fallback
const webpUrl  = buildTransformUrl(BASE, key, "w_800,f_webp,q_80");
const jpegUrl  = buildTransformUrl(BASE, key, "w_800,q_80");

// <picture> tag
// <picture>
//   <source srcSet={webpUrl} type="image/webp" />
//   <img src={jpegUrl} alt="photo" />
// </picture>

// Responsive srcset
const srcset = [400, 800, 1200].map(
  (w) => `${buildTransformUrl(BASE, key, `w_${w},f_webp,q_80`)} ${w}w`
).join(", ");

npm install openinary

import { OpeninaryUploadWidget } from "openinary/upload-widget";

export function MyUploader() {
  return (
    <OpeninaryUploadWidget
      uploadUrl="http://localhost:3000/api/upload"
      authToken={userJwt}
      folder="user-uploads"
      maxFiles={10}
      accept="image/*,video/mp4"
      onSuccess={(assets) => {
        console.log("Uploaded:", assets);
      }}
      onError={(err) => console.error(err)}
    />
  );
}

import { OpeninaryMediaLibrary } from "openinary/media-library";

export function AssetPicker({ onSelect }: { onSelect: (url: string) => void }) {
  return (
    <OpeninaryMediaLibrary
      baseUrl="http://localhost:3000"
      authToken={userJwt}
      mode="modal"            // "modal" | "inline"
      multiSelect={false}
      onSelect={(assets) => onSelect(assets[0].url)}
      onClose={() => {}}
    />
  );
}

import { createHmac, timingSafeEqual } from "crypto";

/**
 * Call this in your webhook handler to verify authenticity.
 * @param rawBody  The raw request body buffer (do NOT parse to JSON first)
 * @param signature  Value of the X-Openinary-Signature header
 * @param secret  Your webhook's signing secret
 */
function verifyWebhook(rawBody: Buffer, signature: string, secret: string): boolean {
  if (!signature.startsWith("sha256=")) return false;
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  try {
    return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch {
    return false;
  }
}

// Next.js App Router example
export async function POST(req: Request) {
  const rawBody = Buffer.from(await req.arrayBuffer());
  const sig = req.headers.get("x-openinary-signature") ?? "";

  if (!verifyWebhook(rawBody, sig, process.env.WEBHOOK_SECRET!)) {
    return new Response("Unauthorized", { status: 401 });
  }

  const payload = JSON.parse(rawBody.toString());

  switch (payload.event) {
    case "upload.complete":
      await indexAsset(payload.data);
      break;
    case "transcode.complete":
      await notifyUser(payload.data.job_id);
      break;
  }

  return new Response(null, { status: 200 });
}

import { OpeninaryClient } from "openinary";

const client = new OpeninaryClient({ baseUrl, apiKey });

// 1. Enqueue a transcoding job
const { job_id } = await client.assets.enqueueTranscode(assetId, {
  format:  "webm",
  width:   1280,
  quality: 28,         // CRF — lower = better quality
  bitrate: "2M",
});

// 2. Poll for completion
async function waitForTranscode(jobId: string, maxWait = 300_000) {
  const start = Date.now();
  while (Date.now() - start < maxWait) {
    const job = await client.assets.getTranscodeJob(jobId);
    if (job.status === "done")   return job.outputUrl;
    if (job.status === "failed") throw new Error(job.error);
    await new Promise((r) => setTimeout(r, 3000));
  }
  throw new Error("Transcode timed out");
}

const outputUrl = await waitForTranscode(job_id);
console.log("Transcoded video:", outputUrl);

// 3. Alternative: listen for the webhook instead of polling
// Set up a webhook for "transcode.complete" and update your DB there.

// 4. Extract a frame (for thumbnails)
const frameUrl = `${baseUrl}/api/asset/${assetId}/frame?t=5.0`;

// 5. Sprite sheet for video preview
const spriteUrl = `${baseUrl}/api/asset/${assetId}/sprite?cols=5&rows=4&thumb_w=160`;