Agency shared stock library

const base = process.env.EPOCHAL_API_BASE ?? "https://epochalstock.com/api/v1";

/** @type {Record<string, string>} projectId -> secret from vault inject */
const projectKeys = {
  // populated at boot from secrets manager — never hardcode real secrets
};

function keyForProject(projectId) {
  const key = projectKeys[projectId] || process.env.EPOCHAL_API_KEY;
  if (!key) throw new Error("no Epochal key configured");
  return key;
}

async function librarySearch(projectId, { q, tags, limit = 24, cursor }) {
  const params = new URLSearchParams({
    sort: q ? "relevance" : "newest",
    limit: String(Math.min(100, limit)),
  });
  if (q) params.set("q", String(q).slice(0, 200));
  if (tags) params.set("tags", tags);
  if (cursor) params.set("cursor", cursor);

  const res = await fetch(\`${base}/images?${params}\`, {
    headers: {
      Authorization: \`Bearer ${keyForProject(projectId)}\`,
      Accept: "application/json",
    },
  });

  const remaining = res.headers.get("x-ratelimit-remaining");
  const reset = res.headers.get("x-ratelimit-reset");
  // metrics.gauge("epochal.remaining", remaining)

  if (res.status === 429) {
    const err = new Error("rate_limit_exceeded");
    err.retryAfter = res.headers.get("retry-after");
    throw err;
  }
  if (!res.ok) throw new Error(await res.text());

  const body = await res.json();
  return {
    images: body.data.images,
    total: body.data.total,
    nextCursor: body.data.next_cursor ?? null,
    rate: { remaining, reset },
    requestId: body.meta?.request_id,
  };
}

<?php
declare(strict_types=1);

function project_api_key(string $projectId): string
{
    // Resolve from secrets manager / encrypted config — example uses env map
    $mapJson = getenv('EPOCHAL_PROJECT_KEYS_JSON') ?: '{}';
    $map = json_decode($mapJson, true, 512, JSON_THROW_ON_ERROR);
    $key = $map[$projectId] ?? getenv('EPOCHAL_API_KEY');
    if (!$key) {
        throw new RuntimeException('no Epochal key for project');
    }
    return $key;
}

function library_search(string $projectId, array $opts): array
{
    $base = rtrim(getenv('EPOCHAL_API_BASE') ?: 'https://epochalstock.com/api/v1', '/');
    $q = substr((string) ($opts['q'] ?? ''), 0, 200);
    $params = [
        'sort' => $q !== '' ? 'relevance' : 'newest',
        'limit' => max(1, min(100, (int) ($opts['limit'] ?? 24))),
    ];
    if ($q !== '') {
        $params['q'] = $q;
    }
    if (!empty($opts['tags'])) {
        $params['tags'] = $opts['tags'];
    }
    if (!empty($opts['cursor'])) {
        $params['cursor'] = $opts['cursor'];
    }

    $ch = curl_init($base . '/images?' . http_build_query($params));
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . project_api_key($projectId),
            'Accept: application/json',
        ],
        CURLOPT_TIMEOUT => 20,
    ]);
    $raw = curl_exec($ch);
    $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $headerSize = (int) curl_getinfo($ch, CURLINFO_HEADER_SIZE);
    curl_close($ch);

    $headers = substr((string) $raw, 0, $headerSize);
    $body = substr((string) $raw, $headerSize);
    if ($status === 429) {
        throw new RuntimeException('rate_limit_exceeded');
    }
    if ($status !== 200) {
        throw new RuntimeException($body);
    }

    $payload = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
    return [
        'images' => $payload['data']['images'],
        'total' => $payload['data']['total'],
        'nextCursor' => $payload['data']['next_cursor'] ?? null,
        'headers' => $headers,
    ];
}

import json
import os
from typing import Any, Optional

import requests

BASE = os.environ.get("EPOCHAL_API_BASE", "https://epochalstock.com/api/v1").rstrip("/")


def project_api_key(project_id: str) -> str:
    raw = os.environ.get("EPOCHAL_PROJECT_KEYS_JSON", "{}")
    mapping = json.loads(raw)
    key = mapping.get(project_id) or os.environ.get("EPOCHAL_API_KEY")
    if not key:
        raise RuntimeError("no Epochal key for project")
    return key


def library_search(
    project_id: str,
    *,
    q: str = "",
    tags: Optional[str] = None,
    limit: int = 24,
    cursor: Optional[str] = None,
) -> dict[str, Any]:
    params: dict[str, Any] = {
        "sort": "relevance" if q else "newest",
        "limit": max(1, min(100, limit)),
    }
    if q:
        params["q"] = q[:200]
    if tags:
        params["tags"] = tags
    if cursor:
        params["cursor"] = cursor

    r = requests.get(
        f"{BASE}/images",
        params=params,
        headers={
            "Authorization": f"Bearer {project_api_key(project_id)}",
            "Accept": "application/json",
        },
        timeout=20,
    )
    # Observe shared budget
    remaining = r.headers.get("X-RateLimit-Remaining")
    if r.status_code == 429:
        raise RuntimeError(f"rate_limit_exceeded retry_after={r.headers.get('Retry-After')}")
    r.raise_for_status()
    data = r.json()["data"]
    return {
        "images": data["images"],
        "total": data["total"],
        "nextCursor": data.get("next_cursor"),
        "remaining": remaining,
    }

async function inventorySnapshot(apiKey) {
  const headers = {
    Authorization: \`Bearer ${apiKey}\`,
    Accept: "application/json",
  };
  const [statsRes, tagsRes] = await Promise.all([
    fetch(\`${base}/stats\`, { headers }),
    fetch(\`${base}/tags?sort=count&order=desc&limit=20\`, { headers }),
  ]);
  // Note: 2 authenticated requests — cache aggressively for ops UI
  if (!statsRes.ok || !tagsRes.ok) {
    throw new Error("inventory_upstream_error");
  }
  const stats = (await statsRes.json()).data;
  const tags = (await tagsRes.json()).data;
  return {
    totalImages: stats.total_images,
    totalTags: stats.total_tags,
    catalogBuiltAt: stats.catalog_built_at,
    topTags: tags.tags ?? tags, // shape per API envelope
  };
}

function inventory_snapshot(string $base, string $apiKey): array
{
    $headers = [
        'Authorization: Bearer ' . $apiKey,
        'Accept: application/json',
    ];
    $fetch = static function (string $url) use ($headers): array {
        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => $headers,
            CURLOPT_TIMEOUT => 20,
        ]);
        $body = curl_exec($ch);
        $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        if ($status !== 200) {
            throw new RuntimeException((string) $body);
        }
        return json_decode((string) $body, true, 512, JSON_THROW_ON_ERROR)['data'];
    };

    $stats = $fetch(rtrim($base, '/') . '/stats');
    $tags = $fetch(rtrim($base, '/') . '/tags?' . http_build_query([
        'sort' => 'count',
        'order' => 'desc',
        'limit' => 20,
    ]));

    return [
        'totalImages' => $stats['total_images'],
        'totalTags' => $stats['total_tags'],
        'catalogBuiltAt' => $stats['catalog_built_at'],
        'topTags' => $tags,
    ];
}

def inventory_snapshot(api_key: str) -> dict:
    headers = {"Authorization": f"Bearer {api_key}", "Accept": "application/json"}
    stats = requests.get(f"{BASE}/stats", headers=headers, timeout=20)
    tags = requests.get(
        f"{BASE}/tags",
        params={"sort": "count", "order": "desc", "limit": 20},
        headers=headers,
        timeout=20,
    )
    stats.raise_for_status()
    tags.raise_for_status()
    s = stats.json()["data"]
    return {
        "totalImages": s["total_images"],
        "totalTags": s["total_tags"],
        "catalogBuiltAt": s["catalog_built_at"],
        "topTags": tags.json()["data"],
    }

import os
import time
import requests

BASE = os.environ.get("EPOCHAL_API_BASE", "https://epochalstock.com/api/v1").rstrip("/")
EXPORT_KEY = os.environ["EPOCHAL_EXPORT_KEY"]


def mint_and_download(image_id: str, attempt: int = 1) -> bytes:
    mint = requests.post(
        f"{BASE}/downloads",
        json={"image_id": image_id},
        headers={
            "Authorization": f"Bearer {EXPORT_KEY}",
            "Content-Type": "application/json",
            "Accept": "application/json",
        },
        timeout=20,
    )
    if mint.status_code == 409:
        if attempt > 10:
            raise RuntimeError("lease_busy")
        time.sleep(min(30, 0.5 * 2 ** (attempt - 1)))
        return mint_and_download(image_id, attempt + 1)
    if mint.status_code == 429:
        time.sleep(float(mint.headers.get("Retry-After", "5")))
        return mint_and_download(image_id, attempt + 1)
    mint.raise_for_status()
    url = mint.json()["data"]["download_url"]
    file_res = requests.get(url, timeout=120)  # no Authorization
    file_res.raise_for_status()
    return file_res.content


def process_export_queue(jobs: list[dict]) -> None:
    # One account-wide loop — all clients share the lease
    for job in jobs:
        data = mint_and_download(job["image_id"])
        store_private(job["client_id"], job["image_id"], data)

<?php
// Serial export — one process holds the account download lease
$base = getenv('EPOCHAL_API_BASE') ?: 'https://epochalstock.com/api/v1';
$exportKey = getenv('EPOCHAL_EXPORT_KEY');

function mint_and_download(string $base, string $exportKey, string $imageId, int $attempt = 1): string
{
    $ch = curl_init(rtrim($base, '/') . '/downloads');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $exportKey,
            'Content-Type: application/json',
            'Accept: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode(['image_id' => $imageId], JSON_THROW_ON_ERROR),
        CURLOPT_TIMEOUT => 20,
    ]);
    $raw = curl_exec($ch);
    $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($status === 409) {
        if ($attempt > 10) {
            throw new RuntimeException('lease_busy');
        }
        usleep((int) (min(30_000, 500 * (2 ** ($attempt - 1)))) * 1000);
        return mint_and_download($base, $exportKey, $imageId, $attempt + 1);
    }
    if ($status === 429) {
        sleep(5);
        return mint_and_download($base, $exportKey, $imageId, $attempt + 1);
    }
    if ($status !== 201) {
        throw new RuntimeException((string) $raw);
    }

    $url = json_decode((string) $raw, true, 512, JSON_THROW_ON_ERROR)['data']['download_url'];
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_TIMEOUT => 120,
    ]);
    $bytes = curl_exec($ch);
    $dl = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($dl !== 200) {
        throw new RuntimeException('download failed');
    }
    return (string) $bytes;
}

# Mint then download without the key — run jobs one after another
API_BASE="${EPOCHAL_API_BASE:-https://epochalstock.com/api/v1}"
mint=$(curl -sS -X POST "$API_BASE/downloads" \
  -H "Authorization: Bearer $EPOCHAL_EXPORT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_id":"es_001_example"}')
# parse download_url from JSON, then:
# curl -fL "$DOWNLOAD_URL" -o acme/es_001_example.bin
# On 409: wait for the active transfer to finish, then retry mint.