Print & POD mockup source pipeline

const base = process.env.EPOCHAL_API_BASE ?? "https://epochalstock.com/api/v1";
const apiKey = process.env.EPOCHAL_API_KEY;
if (!apiKey) throw new Error("Set EPOCHAL_API_KEY on the POD backend");

/** Operator-facing search — session auth happens in your framework */
async function searchAssets({ q, tags, tagMode = "all", sort = "relevance", limit = 30, cursor }) {
  const params = new URLSearchParams({ sort, limit: String(limit) });
  if (q) params.set("q", String(q).slice(0, 200));
  if (tags) {
    const list = Array.isArray(tags) ? tags : String(tags).split(",");
    params.set("tags", list.map((t) => t.trim()).filter(Boolean).slice(0, 20).join(","));
    params.set("tag_mode", tagMode === "any" ? "any" : "all");
  }
  if (cursor) params.set("cursor", cursor);

  const res = await fetch(`${base}/images?${params}`, {
    headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
  });
  if (res.status === 429) {
    const wait = Number(res.headers.get("Retry-After") || "2");
    await new Promise((r) => setTimeout(r, wait * 1000));
    return searchAssets({ q, tags, tagMode, sort, limit, cursor });
  }
  if (!res.ok) throw new Error(await res.text());
  const { data, meta } = await res.json();
  // Return only preview fields to the operator UI
  return {
    images: data.images.map((img) => ({
      id: img.id,
      title: img.title,
      width: img.width,
      height: img.height,
      extension: img.extension,
      tags: img.tags,
      thumbnail_url: img.thumbnail_url,
      preview_url: img.preview_url,
    })),
    total: data.total,
    nextCursor: data.next_cursor ?? null,
    requestId: meta?.request_id,
  };
}

<?php
declare(strict_types=1);

$base = rtrim(getenv('EPOCHAL_API_BASE') ?: 'https://epochalstock.com/api/v1', '/');
$apiKey = getenv('EPOCHAL_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set EPOCHAL_API_KEY on the POD backend');
}

/**
 * @param array{q?:string,tags?:list<string>|string,tag_mode?:string,sort?:string,limit?:int,cursor?:string} $opts
 * @return array<string,mixed>
 */
function search_assets(string $base, string $apiKey, array $opts): array
{
    $params = [
        'sort' => $opts['sort'] ?? 'relevance',
        'limit' => $opts['limit'] ?? 30,
    ];
    if (!empty($opts['q'])) {
        $params['q'] = substr((string) $opts['q'], 0, 200);
    }
    if (!empty($opts['tags'])) {
        $tags = is_array($opts['tags']) ? $opts['tags'] : explode(',', (string) $opts['tags']);
        $tags = array_slice(array_values(array_filter(array_map('trim', $tags))), 0, 20);
        if ($tags) {
            $params['tags'] = implode(',', $tags);
            $params['tag_mode'] = (($opts['tag_mode'] ?? 'all') === 'any') ? 'any' : 'all';
        }
    }
    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_HTTPHEADER => [
            'Authorization: Bearer ' . $apiKey,
            'Accept: application/json',
        ],
        CURLOPT_TIMEOUT => 20,
    ]);
    $raw = curl_exec($ch);
    $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($status === 429) {
        sleep(2);
        return search_assets($base, $apiKey, $opts);
    }
    if ($status !== 200) {
        throw new RuntimeException((string) $raw);
    }
    return json_decode((string) $raw, true, 512, JSON_THROW_ON_ERROR)['data'];
}

import os
import time
import requests

base = os.environ.get("EPOCHAL_API_BASE", "https://epochalstock.com/api/v1").rstrip("/")
api_key = os.environ["EPOCHAL_API_KEY"]


def search_assets(*, q=None, tags=None, tag_mode="all", sort="relevance", limit=30, cursor=None):
    params = {"sort": sort, "limit": limit}
    if q:
        params["q"] = q[:200]
    if tags:
        if isinstance(tags, list):
            tags = ",".join(tags[:20])
        params["tags"] = tags
        params["tag_mode"] = "any" if tag_mode == "any" else "all"
    if cursor:
        params["cursor"] = cursor

    r = requests.get(
        f"{base}/images",
        params=params,
        headers={"Authorization": f"Bearer {api_key}", "Accept": "application/json"},
        timeout=20,
    )
    if r.status_code == 429:
        time.sleep(int(r.headers.get("Retry-After", "2")))
        return search_assets(q=q, tags=tags, tag_mode=tag_mode, sort=sort, limit=limit, cursor=cursor)
    r.raise_for_status()
    return r.json()["data"]

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
    "strings"
    "time"
)

func searchAssets(base, apiKey, q string, tags []string, limit int, cursor string) (map[string]any, error) {
    v := url.Values{}
    v.Set("sort", "relevance")
    v.Set("limit", fmt.Sprintf("%d", limit))
    if q != "" {
        if len(q) > 200 {
            q = q[:200]
        }
        v.Set("q", q)
    }
    if len(tags) > 0 {
        if len(tags) > 20 {
            tags = tags[:20]
        }
        v.Set("tags", strings.Join(tags, ","))
        v.Set("tag_mode", "all")
    }
    if cursor != "" {
        v.Set("cursor", cursor)
    }
    req, _ := http.NewRequest(http.MethodGet, strings.TrimRight(base, "/")+"/images?"+v.Encode(), nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Accept", "application/json")
    res, err := (&http.Client{Timeout: 20 * time.Second}).Do(req)
    if err != nil {
        return nil, err
    }
    defer res.Body.Close()
    b, _ := io.ReadAll(res.Body)
    if res.StatusCode != 200 {
        return nil, fmt.Errorf("search %d: %s", res.StatusCode, b)
    }
    var payload map[string]any
    if err := json.Unmarshal(b, &payload); err != nil {
        return nil, err
    }
    return payload["data"].(map[string]any), nil
}

func main() {
    base := os.Getenv("EPOCHAL_API_BASE")
    if base == "" {
        base = "https://epochalstock.com/api/v1"
    }
    _ = base
}

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

async function preflight(ids) {
  const unique = [...new Set(ids)];
  const images = [];
  for (let i = 0; i < unique.length; i += 100) {
    const chunk = unique.slice(i, i + 100);
    const res = await fetch(`${base}/images/batch`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.EPOCHAL_API_KEY}`,
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify({ ids: chunk }),
    });
    if (!res.ok) throw new Error(await res.text());
    const { data } = await res.json();
    images.push(...data.images);
    // data.found / data.requested — drop missing IDs from the export queue
  }
  return images;
}

<?php
function preflight(string $base, string $apiKey, array $ids): array
{
    $unique = array_values(array_unique($ids));
    $images = [];
    foreach (array_chunk($unique, 100) as $chunk) {
        $ch = curl_init(rtrim($base, '/') . '/images/batch');
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST => true,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . $apiKey,
                'Content-Type: application/json',
                'Accept: application/json',
            ],
            CURLOPT_POSTFIELDS => json_encode(['ids' => $chunk], JSON_THROW_ON_ERROR),
            CURLOPT_TIMEOUT => 20,
        ]);
        $raw = curl_exec($ch);
        $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        if ($status !== 200) {
            throw new RuntimeException((string) $raw);
        }
        $data = json_decode((string) $raw, true, 512, JSON_THROW_ON_ERROR)['data'];
        foreach ($data['images'] as $img) {
            $images[] = $img;
        }
    }
    return $images;
}

import os
import requests

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


def preflight(ids: list[str]) -> list[dict]:
    unique = list(dict.fromkeys(ids))
    images: list[dict] = []
    for i in range(0, len(unique), 100):
        chunk = unique[i : i + 100]
        r = requests.post(
            f"{base}/images/batch",
            json={"ids": chunk},
            headers={
                "Authorization": f"Bearer {os.environ['EPOCHAL_API_KEY']}",
                "Accept": "application/json",
            },
            timeout=20,
        )
        r.raise_for_status()
        data = r.json()["data"]
        images.extend(data["images"])
        # inspect data["found"], data["requested"]
    return images

<?php
declare(strict_types=1);

$base = rtrim(getenv('EPOCHAL_API_BASE') ?: 'https://epochalstock.com/api/v1', '/');
$apiKey = getenv('EPOCHAL_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set EPOCHAL_API_KEY');
}

function mint_and_download(string $base, string $apiKey, string $imageId, string $destPath, int $attempt = 1): void
{
    $ch = curl_init(rtrim($base, '/') . '/downloads');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiKey,
            '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 >= 8) {
            throw new RuntimeException('lease busy too long');
        }
        usleep((int) ((500 * (2 ** ($attempt - 1))) + random_int(0, 250)) * 1000);
        mint_and_download($base, $apiKey, $imageId, $destPath, $attempt + 1);
        return;
    }
    if ($status === 429) {
        sleep(5);
        mint_and_download($base, $apiKey, $imageId, $destPath, $attempt + 1);
        return;
    }
    if ($status === 404) {
        throw new RuntimeException('permanent failure: ' . (string) $raw);
    }
    if ($status !== 201) {
        throw new RuntimeException('mint failed: ' . (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: ' . $dl);
    }
    file_put_contents($destPath, $bytes);
}

/** YOUR compositor — not Epochal */
function render_mockup(string $originalPath, string $templateId, string $productId): string
{
    // Invoke ImageMagick, a PDF engine, etc.
    return '/var/pod/mockups/' . $productId . '.jpg';
}

/**
 * @param list<array{image_id:string,product_id:string,template_id:string}> $jobs
 */
function run_export_queue(string $base, string $apiKey, array $jobs, string $storageDir): void
{
    foreach ($jobs as $job) {
        $dest = rtrim($storageDir, '/\\') . DIRECTORY_SEPARATOR . $job['image_id'] . '.bin';
        mint_and_download($base, $apiKey, $job['image_id'], $dest);
        render_mockup($dest, $job['template_id'], $job['product_id']);
        // UPDATE pod_jobs SET status = 'composited' …
    }
}

import os
import random
import time
from pathlib import Path

import requests

base = os.environ.get("EPOCHAL_API_BASE", "https://epochalstock.com/api/v1").rstrip("/")
api_key = os.environ["EPOCHAL_API_KEY"]


def mint_and_download(image_id: str, dest: Path, attempt: int = 1) -> None:
    mint = requests.post(
        f"{base}/downloads",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
            "Accept": "application/json",
        },
        json={"image_id": image_id},
        timeout=20,
    )
    if mint.status_code == 409:
        if attempt >= 8:
            raise RuntimeError("lease busy too long")
        time.sleep(min(30, 0.5 * (2 ** (attempt - 1))) + random.random() * 0.25)
        return mint_and_download(image_id, dest, attempt + 1)
    if mint.status_code == 429:
        time.sleep(int(mint.headers.get("Retry-After", "5")))
        return mint_and_download(image_id, dest, attempt + 1)
    if mint.status_code == 404:
        raise RuntimeError(f"permanent: {mint.text}")
    mint.raise_for_status()
    url = mint.json()["data"]["download_url"]
    with requests.get(url, stream=True, timeout=120) as r:
        r.raise_for_status()
        with open(dest, "wb") as f:
            for chunk in r.iter_content(256 * 1024):
                if chunk:
                    f.write(chunk)


def render_mockup(original: Path, template_id: str, product_id: str) -> Path:
    # YOUR mockup pipeline (Pillow, skia, external service, …)
    out = Path("/var/pod/mockups") / f"{product_id}.jpg"
    return out


def run_export_queue(jobs: list[dict], storage_dir: Path) -> None:
    storage_dir.mkdir(parents=True, exist_ok=True)
    for job in jobs:
        dest = storage_dir / f"{job['image_id']}.bin"
        mint_and_download(job["image_id"], dest)
        render_mockup(dest, job["template_id"], job["product_id"])

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "math"
    "math/rand"
    "net/http"
    "os"
    "path/filepath"
    "time"
)

func mintAndDownload(base, apiKey, imageID, dest string, attempt int) error {
    body, _ := json.Marshal(map[string]string{"image_id": imageID})
    req, _ := http.NewRequest(http.MethodPost, base+"/downloads", bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Accept", "application/json")
    res, err := (&http.Client{Timeout: 20 * time.Second}).Do(req)
    if err != nil {
        return err
    }
    defer res.Body.Close()
    if res.StatusCode == 409 {
        if attempt >= 8 {
            return fmt.Errorf("lease busy too long")
        }
        wait := time.Duration(math.Min(30, 0.5*math.Pow(2, float64(attempt-1)))*1000) * time.Millisecond
        time.Sleep(wait + time.Duration(rand.Intn(250))*time.Millisecond)
        return mintAndDownload(base, apiKey, imageID, dest, attempt+1)
    }
    if res.StatusCode == 429 {
        time.Sleep(5 * time.Second)
        return mintAndDownload(base, apiKey, imageID, dest, attempt+1)
    }
    if res.StatusCode != http.StatusCreated {
        b, _ := io.ReadAll(res.Body)
        return fmt.Errorf("mint %d: %s", res.StatusCode, b)
    }
    var payload struct {
        Data struct {
            DownloadURL string `json:"download_url"`
        } `json:"data"`
    }
    if err := json.NewDecoder(res.Body).Decode(&payload); err != nil {
        return err
    }
    dl, err := (&http.Client{Timeout: 120 * time.Second}).Get(payload.Data.DownloadURL)
    if err != nil {
        return err
    }
    defer dl.Body.Close()
    f, err := os.Create(dest)
    if err != nil {
        return err
    }
    defer f.Close()
    _, err = io.Copy(f, dl.Body)
    return err
}

// renderMockup is YOUR code — Epochal has no composite endpoint
func renderMockup(originalPath, templateID, productID string) error {
    _ = originalPath
    _ = templateID
    _ = productID
    return nil
}

func runExportQueue(base, apiKey string, jobs []struct{ ImageID, ProductID, TemplateID string }, dir string) error {
    for _, job := range jobs {
        dest := filepath.Join(dir, job.ImageID+".bin")
        if err := mintAndDownload(base, apiKey, job.ImageID, dest, 1); err != nil {
            return err
        }
        if err := renderMockup(dest, job.TemplateID, job.ProductID); err != nil {
            return err
        }
    }
    return nil
}

# Per job, serially:
curl -sS -X POST "https://epochalstock.com/api/v1/downloads" \
  -H "Authorization: Bearer $EPOCHAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_id":"es_001_example"}'
# Parse data.download_url from 201 JSON, then:
curl -fL "$DOWNLOAD_URL" -o "es_001_example.bin"
# On HTTP 409: wait and retry mint. Do not parallelize on one account.
# Then run YOUR mockup CLI against the saved file.