@donotlb/imagen-sdk 0.2.0

package/dist/callback.d.ts

@@ -0,0 +1,13 @@
+import type { ImagenCallbackPayload } from './contracts.js';
+export declare class ImagenCallbackVerificationError extends Error {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class ImagenCallbackParseError extends Error {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function parseImagenCallback(body: unknown): ImagenCallbackPayload;
+export declare function verifyImagenCallbackRequest(headers: Headers | Record<string, string | undefined>, secret: string, clientName?: string): Promise<void>;

package/dist/callback.js

@@ -0,0 +1,46 @@
+import { imagenCallbackPayloadSchema } from './contracts.js';
+import { verifyImagenCallbackJwt } from './service-jwt.js';
+export class ImagenCallbackVerificationError extends Error {
+    constructor(message = 'Invalid Imagen callback request', options = {}) {
+        super(message, options);
+        this.name = 'ImagenCallbackVerificationError';
+    }
+}
+export class ImagenCallbackParseError extends Error {
+    constructor(message = 'Invalid Imagen callback payload', options = {}) {
+        super(message, options);
+        this.name = 'ImagenCallbackParseError';
+    }
+}
+function getHeader(headers, name) {
+    if (headers instanceof Headers)
+        return headers.get(name);
+    const lower = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === lower)
+            return value ?? null;
+    }
+    return null;
+}
+function bearerToken(authorization) {
+    const [scheme, token] = authorization?.split(/\s+/u) ?? [];
+    if (scheme?.toLowerCase() !== 'bearer' || !token)
+        throw new ImagenCallbackVerificationError('Imagen callback bearer token is required');
+    return token;
+}
+export function parseImagenCallback(body) {
+    const parsed = imagenCallbackPayloadSchema.safeParse(body);
+    if (!parsed.success)
+        throw new ImagenCallbackParseError('Invalid Imagen callback payload', { cause: parsed.error });
+    return parsed.data;
+}
+export async function verifyImagenCallbackRequest(headers, secret, clientName) {
+    try {
+        await verifyImagenCallbackJwt(bearerToken(getHeader(headers, 'authorization')), secret, clientName);
+    }
+    catch (error) {
+        if (error instanceof ImagenCallbackVerificationError)
+            throw error;
+        throw new ImagenCallbackVerificationError('Invalid Imagen callback token', { cause: error });
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+import type { ImagenGenerationAccepted, ImagenGenerationCancelAccepted, ImagenGenerationCancelRequest, ImagenGenerationRequest } from './contracts.js';
+export interface ImagenClientOptions {
+    baseUrl: string;
+    serviceJwtSecret: string;
+    /** This caller's service identity (JWT `iss`). Defaults to `tutu`. */
+    clientName?: string;
+    fetch?: typeof fetch;
+}
+export declare class ImagenClientError extends Error {
+    readonly status: number | null;
+    readonly retryable: boolean;
+    readonly responseBody: string | null;
+    constructor(message: string, options: {
+        status?: number | null;
+        retryable: boolean;
+        responseBody?: string | null;
+        cause?: unknown;
+    });
+}
+export declare class ImagenPayloadMismatchError extends ImagenClientError {
+    constructor(message: string, options?: {
+        responseBody?: string | null;
+    });
+}
+export declare class ImagenClient {
+    private readonly baseUrl;
+    private readonly serviceJwtSecret;
+    private readonly clientName;
+    private readonly fetchImpl;
+    constructor(options: ImagenClientOptions);
+    createGeneration(request: ImagenGenerationRequest): Promise<ImagenGenerationAccepted>;
+    cancelGeneration(request: ImagenGenerationCancelRequest): Promise<ImagenGenerationCancelAccepted>;
+}

package/dist/client.js

@@ -0,0 +1,111 @@
+import { imagenGenerationAcceptedSchema, imagenGenerationCancelAcceptedSchema } from './contracts.js';
+import { DEFAULT_SERVICE_CLIENT_NAME, signClientToImagenJwt } from './service-jwt.js';
+export class ImagenClientError extends Error {
+    status;
+    retryable;
+    responseBody;
+    constructor(message, options) {
+        super(message, { cause: options.cause });
+        this.name = 'ImagenClientError';
+        this.status = options.status ?? null;
+        this.retryable = options.retryable;
+        this.responseBody = options.responseBody ?? null;
+    }
+}
+export class ImagenPayloadMismatchError extends ImagenClientError {
+    constructor(message, options = {}) {
+        super(message, {
+            status: 409,
+            retryable: false,
+            responseBody: options.responseBody ?? null,
+        });
+        this.name = 'ImagenPayloadMismatchError';
+    }
+}
+export class ImagenClient {
+    baseUrl;
+    serviceJwtSecret;
+    clientName;
+    fetchImpl;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/u, '');
+        this.serviceJwtSecret = options.serviceJwtSecret;
+        this.clientName = options.clientName ?? DEFAULT_SERVICE_CLIENT_NAME;
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    async createGeneration(request) {
+        const token = await signClientToImagenJwt(this.serviceJwtSecret, this.clientName);
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.baseUrl}/api/generations`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${token}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(request),
+            });
+        }
+        catch (error) {
+            throw new ImagenClientError('Imagen generation request failed', {
+                retryable: true,
+                cause: error,
+            });
+        }
+        if (response.status === 200 || response.status === 202) {
+            const parsed = imagenGenerationAcceptedSchema.safeParse(await response.json());
+            if (!parsed.success) {
+                throw new ImagenClientError('Imagen accepted the generation but returned an invalid response', {
+                    status: response.status,
+                    retryable: true,
+                });
+            }
+            return parsed.data;
+        }
+        const text = await response.text();
+        const message = `Imagen generation request failed (${response.status}): ${text.slice(0, 500)}`;
+        if (response.status === 409)
+            throw new ImagenPayloadMismatchError(message, { responseBody: text });
+        throw new ImagenClientError(message, {
+            status: response.status,
+            retryable: response.status >= 500,
+            responseBody: text,
+        });
+    }
+    async cancelGeneration(request) {
+        const token = await signClientToImagenJwt(this.serviceJwtSecret, this.clientName);
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.baseUrl}/api/generations/cancel`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${token}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(request),
+            });
+        }
+        catch (error) {
+            throw new ImagenClientError('Imagen generation cancellation request failed', {
+                retryable: true,
+                cause: error,
+            });
+        }
+        if (response.status === 200 || response.status === 202) {
+            const parsed = imagenGenerationCancelAcceptedSchema.safeParse(await response.json());
+            if (!parsed.success) {
+                throw new ImagenClientError('Imagen accepted the cancellation but returned an invalid response', {
+                    status: response.status,
+                    retryable: true,
+                });
+            }
+            return parsed.data;
+        }
+        const text = await response.text();
+        throw new ImagenClientError(`Imagen generation cancellation request failed (${response.status}): ${text.slice(0, 500)}`, {
+            status: response.status,
+            retryable: response.status >= 500,
+            responseBody: text,
+        });
+    }
+}

package/dist/contracts.d.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+export declare const imageGenerationTypeSchema: z.ZodEnum<{
+    "image.generate": "image.generate";
+    "image.edit": "image.edit";
+}>;
+export declare const imagenGenerationRequestSchema: z.ZodObject<{
+    idempotencyKey: z.ZodString;
+    externalJobId: z.ZodString;
+    type: z.ZodEnum<{
+        "image.generate": "image.generate";
+        "image.edit": "image.edit";
+    }>;
+    input: z.ZodObject<{
+        prompt: z.ZodString;
+        model: z.ZodEnum<{
+            "openai/gpt-image-2": "openai/gpt-image-2";
+        }>;
+        quality: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>;
+        resolution: z.ZodEnum<{
+            "1k": "1k";
+            "2k": "2k";
+            "4k": "4k";
+        }>;
+        aspectRatio: z.ZodEnum<{
+            auto: "auto";
+            "1:1": "1:1";
+            "2:3": "2:3";
+            "3:2": "3:2";
+            "3:4": "3:4";
+            "4:3": "4:3";
+            "4:5": "4:5";
+            "5:4": "5:4";
+            "9:16": "9:16";
+            "16:9": "16:9";
+            "21:9": "21:9";
+        }>;
+        inputImages: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            url: z.ZodURL;
+            contentType: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        count: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        storageKeyPrefix: z.ZodString;
+    }, z.core.$strict>;
+    callback: z.ZodObject<{
+        url: z.ZodURL;
+    }, z.core.$strict>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const imagenGenerationAcceptedSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    externalJobId: z.ZodString;
+    status: z.ZodEnum<{
+        accepted: "accepted";
+        duplicate: "duplicate";
+    }>;
+}, z.core.$strict>;
+export declare const imagenGenerationCancelRequestSchema: z.ZodObject<{
+    externalJobId: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const imagenGenerationCancelAcceptedSchema: z.ZodObject<{
+    jobId: z.ZodNullable<z.ZodString>;
+    externalJobId: z.ZodString;
+    status: z.ZodEnum<{
+        cancelled: "cancelled";
+        already_terminal: "already_terminal";
+        not_found: "not_found";
+    }>;
+}, z.core.$strict>;
+export declare const imagenCallbackPayloadSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    externalJobId: z.ZodString;
+    status: z.ZodEnum<{
+        succeeded: "succeeded";
+        failed: "failed";
+    }>;
+    outputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        storageKey: z.ZodString;
+        url: z.ZodURL;
+        contentType: z.ZodString;
+        width: z.ZodNullable<z.ZodNumber>;
+        height: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    provider: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        model: z.ZodString;
+        responseId: z.ZodOptional<z.ZodString>;
+        costUsdMicros: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        retryable: z.ZodBoolean;
+    }, z.core.$strict>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export type ImageGenerationType = z.infer<typeof imageGenerationTypeSchema>;
+export type ImagenGenerationRequest = z.infer<typeof imagenGenerationRequestSchema>;
+export type ImagenGenerationAccepted = z.infer<typeof imagenGenerationAcceptedSchema>;
+export type ImagenGenerationCancelRequest = z.infer<typeof imagenGenerationCancelRequestSchema>;
+export type ImagenGenerationCancelAccepted = z.infer<typeof imagenGenerationCancelAcceptedSchema>;
+export type ImagenCallbackPayload = z.infer<typeof imagenCallbackPayloadSchema>;
+export interface CallbackJobPayload {
+    jobId: string;
+    url: string;
+    body: ImagenCallbackPayload;
+}

package/dist/contracts.js

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { ASPECT_RATIOS, IMAGE_MODEL_IDS, IMAGE_QUALITIES, RESOLUTIONS, } from './image-models/index.js';
+export const imageGenerationTypeSchema = z.enum(['image.generate', 'image.edit']);
+export const imagenGenerationRequestSchema = z.object({
+    idempotencyKey: z.string().trim().min(1).max(200),
+    externalJobId: z.string().trim().min(1).max(200),
+    type: imageGenerationTypeSchema,
+    input: z.object({
+        prompt: z.string().trim().min(1).max(20_000),
+        model: z.enum(IMAGE_MODEL_IDS),
+        quality: z.enum(IMAGE_QUALITIES),
+        resolution: z.enum(RESOLUTIONS),
+        aspectRatio: z.enum(ASPECT_RATIOS),
+        inputImages: z.array(z.object({
+            url: z.url(),
+            contentType: z.string().trim().min(1).max(200).optional(),
+        }).strict()).max(16).optional(),
+        count: z.int().min(1).max(4).optional(),
+    }).strict(),
+    output: z.object({
+        // Opaque namespace owned by the caller. Imagen does not interpret its
+        // structure; it only normalizes it and owns the leaf filename
+        // (`${jobId}-${index}.${ext}`). Callers should treat the returned
+        // `storageKey` as a read-only opaque value.
+        storageKeyPrefix: z.string().trim().min(1).max(1024),
+    }).strict(),
+    callback: z.object({
+        url: z.url(),
+    }).strict(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+export const imagenGenerationAcceptedSchema = z.object({
+    jobId: z.string(),
+    externalJobId: z.string(),
+    status: z.enum(['accepted', 'duplicate']),
+}).strict();
+export const imagenGenerationCancelRequestSchema = z.object({
+    externalJobId: z.string().trim().min(1).max(200),
+    reason: z.string().trim().min(1).max(200).optional(),
+}).strict();
+export const imagenGenerationCancelAcceptedSchema = z.object({
+    jobId: z.string().nullable(),
+    externalJobId: z.string(),
+    status: z.enum(['cancelled', 'already_terminal', 'not_found']),
+}).strict();
+export const imagenCallbackPayloadSchema = z.object({
+    jobId: z.string(),
+    externalJobId: z.string(),
+    status: z.enum(['succeeded', 'failed']),
+    outputs: z.array(z.object({
+        storageKey: z.string(),
+        url: z.url(),
+        contentType: z.string(),
+        width: z.number().int().positive().nullable(),
+        height: z.number().int().positive().nullable(),
+    }).strict()).optional(),
+    provider: z.object({
+        name: z.string(),
+        model: z.string(),
+        responseId: z.string().optional(),
+        costUsdMicros: z.number().int().nonnegative().optional(),
+    }).strict().optional(),
+    error: z.object({
+        code: z.string(),
+        message: z.string(),
+        retryable: z.boolean(),
+    }).strict().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();

package/dist/image-models/index.d.ts

@@ -0,0 +1,6 @@
+export type { ImageModelSpec, SizeConstraints } from './registry.js';
+export { getModelSpec } from './registry.js';
+export type { ResolvedSize } from './size.js';
+export { formatSize, resolveImageSize } from './size.js';
+export type { AspectRatio, ImageModelId, ImageQuality, Resolution, } from './types.js';
+export { ASPECT_RATIOS, IMAGE_MODEL_IDS, IMAGE_QUALITIES, RESOLUTIONS, } from './types.js';

package/dist/image-models/index.js

@@ -0,0 +1,3 @@
+export { getModelSpec } from './registry.js';
+export { formatSize, resolveImageSize } from './size.js';
+export { ASPECT_RATIOS, IMAGE_MODEL_IDS, IMAGE_QUALITIES, RESOLUTIONS, } from './types.js';

package/dist/image-models/registry.d.ts

@@ -0,0 +1,30 @@
+import type { AspectRatio, ImageModelId, ImageQuality, Resolution } from './types.js';
+/**
+ * The provider's hard limits on an output size; size derivation honours all of
+ * these. {@link ImageModelSpec.resolutionLongEdge} and {@link SizeConstraints.maxPixels}
+ * together bound the worst-case (largest) pixel count of a resolution tier.
+ */
+export interface SizeConstraints {
+    /** Longest edge the provider accepts, in pixels. */
+    maxEdge: number;
+    /** Both edges must be a multiple of this. */
+    edgeMultiple: number;
+    minPixels: number;
+    maxPixels: number;
+    /** Long edge / short edge must not exceed this. */
+    maxAspectRatio: number;
+}
+export interface ImageModelSpec {
+    id: ImageModelId;
+    qualities: readonly ImageQuality[];
+    resolutions: readonly Resolution[];
+    aspectRatios: readonly AspectRatio[];
+    constraints: SizeConstraints;
+    /**
+     * Target long-edge (px) each resolution tier aims for before the constraints
+     * clamp it. Square/near-square 4K is pulled below 3840 by the pixel ceiling;
+     * thin ratios at 1K are pushed up by the pixel floor.
+     */
+    resolutionLongEdge: Record<Resolution, number>;
+}
+export declare function getModelSpec(model: ImageModelId): ImageModelSpec;

package/dist/image-models/registry.js

@@ -0,0 +1,27 @@
+import { ASPECT_RATIOS, IMAGE_QUALITIES, RESOLUTIONS } from './types.js';
+// gpt-image-2 constraints, from OpenAI's image generation guide: max edge 3840,
+// edges multiple of 16, long:short <= 3:1, total pixels in [655_360, 8_294_400].
+const GPT_IMAGE_2 = {
+    id: 'openai/gpt-image-2',
+    qualities: IMAGE_QUALITIES,
+    resolutions: RESOLUTIONS,
+    aspectRatios: ASPECT_RATIOS,
+    constraints: {
+        maxEdge: 3840,
+        edgeMultiple: 16,
+        minPixels: 655_360,
+        maxPixels: 8_294_400,
+        maxAspectRatio: 3,
+    },
+    resolutionLongEdge: {
+        '1k': 1024,
+        '2k': 2048,
+        '4k': 3840,
+    },
+};
+const SPECS = {
+    'openai/gpt-image-2': GPT_IMAGE_2,
+};
+export function getModelSpec(model) {
+    return SPECS[model];
+}

package/dist/image-models/size.d.ts

@@ -0,0 +1,23 @@
+import type { AspectRatio, ImageModelId, Resolution } from './types.js';
+export interface ResolvedSize {
+    width: number;
+    height: number;
+}
+/**
+ * Derive the concrete pixel size to request for a (ratio, resolution) choice,
+ * honouring every model constraint: the resolution tier sets a target long
+ * edge, which is then clamped into the pixel floor/ceiling and rounded so both
+ * edges are a valid multiple. The long edge is anchored to the tier, so the
+ * canonical OpenAI sizes fall out exactly (e.g. 2K 16:9 -> 2048x1152, 4K 16:9
+ * -> 3840x2160), while squarer ratios at 4K are pulled down by the 8.29MP
+ * ceiling and thin ratios at 1K are pushed up by the 655K floor.
+ *
+ * `auto` ratio resolves to a square (1:1) at the chosen resolution: the
+ * resolution selector is always honoured and the billed tier always matches the
+ * pixels actually requested. (gpt-image-2's own `size: auto` would let the model
+ * pick the aspect but ignore our resolution choice, so we default the aspect
+ * ourselves instead.)
+ */
+export declare function resolveImageSize(model: ImageModelId, aspectRatio: AspectRatio, resolution: Resolution): ResolvedSize;
+/** Format a resolved size as the provider's `WIDTHxHEIGHT` size string. */
+export declare function formatSize(size: ResolvedSize | 'auto'): string;

package/dist/image-models/size.js

@@ -0,0 +1,64 @@
+import { getModelSpec } from './registry.js';
+function roundToMultiple(value, multiple) {
+    return Math.max(multiple, Math.round(value / multiple) * multiple);
+}
+/**
+ * Derive the concrete pixel size to request for a (ratio, resolution) choice,
+ * honouring every model constraint: the resolution tier sets a target long
+ * edge, which is then clamped into the pixel floor/ceiling and rounded so both
+ * edges are a valid multiple. The long edge is anchored to the tier, so the
+ * canonical OpenAI sizes fall out exactly (e.g. 2K 16:9 -> 2048x1152, 4K 16:9
+ * -> 3840x2160), while squarer ratios at 4K are pulled down by the 8.29MP
+ * ceiling and thin ratios at 1K are pushed up by the 655K floor.
+ *
+ * `auto` ratio resolves to a square (1:1) at the chosen resolution: the
+ * resolution selector is always honoured and the billed tier always matches the
+ * pixels actually requested. (gpt-image-2's own `size: auto` would let the model
+ * pick the aspect but ignore our resolution choice, so we default the aspect
+ * ourselves instead.)
+ */
+export function resolveImageSize(model, aspectRatio, resolution) {
+    const { constraints: c, resolutionLongEdge } = getModelSpec(model);
+    const [rw, rh] = aspectRatio === 'auto'
+        ? [1, 1]
+        : aspectRatio.split(':').map(Number);
+    const ratioLong = Math.max(rw, rh);
+    const ratioShort = Math.min(rw, rh);
+    let longEdge = resolutionLongEdge[resolution];
+    let shortEdge = (longEdge * ratioShort) / ratioLong;
+    // Scale into the pixel band before rounding.
+    const pixels = longEdge * shortEdge;
+    if (pixels > c.maxPixels) {
+        const scale = Math.sqrt(c.maxPixels / pixels);
+        longEdge *= scale;
+        shortEdge *= scale;
+    }
+    else if (pixels < c.minPixels) {
+        const scale = Math.sqrt(c.minPixels / pixels);
+        longEdge *= scale;
+        shortEdge *= scale;
+    }
+    longEdge = roundToMultiple(Math.min(longEdge, c.maxEdge), c.edgeMultiple);
+    shortEdge = roundToMultiple(shortEdge, c.edgeMultiple);
+    // Rounding can nudge past the ceiling/floor; step back into range.
+    while (longEdge * shortEdge > c.maxPixels) {
+        if (longEdge >= shortEdge)
+            longEdge -= c.edgeMultiple;
+        else
+            shortEdge -= c.edgeMultiple;
+    }
+    while (longEdge * shortEdge < c.minPixels) {
+        shortEdge += c.edgeMultiple;
+        if (shortEdge > longEdge && ratioLong !== ratioShort) {
+            shortEdge -= c.edgeMultiple;
+            longEdge += c.edgeMultiple;
+        }
+    }
+    return rw >= rh
+        ? { width: longEdge, height: shortEdge }
+        : { width: shortEdge, height: longEdge };
+}
+/** Format a resolved size as the provider's `WIDTHxHEIGHT` size string. */
+export function formatSize(size) {
+    return size === 'auto' ? 'auto' : `${size.width}x${size.height}`;
+}

package/dist/image-models/types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Canonical image-model vocabulary for the Imagen service contract — the
+ * aspect-ratio / resolution / quality unions defined exactly once and shared by
+ * every consumer (the Imagen service and its SDK clients).
+ *
+ * `quality` is deliberately three tiers — `auto` was dropped at the product
+ * layer (callers should pick a concrete tier before submitting work to Imagen).
+ * A consumer's database may keep a legacy `auto` enum value for historical rows,
+ * but nothing new is written with it.
+ */
+export declare const IMAGE_MODEL_IDS: readonly ["openai/gpt-image-2"];
+export type ImageModelId = typeof IMAGE_MODEL_IDS[number];
+export declare const IMAGE_QUALITIES: readonly ["low", "medium", "high"];
+export type ImageQuality = typeof IMAGE_QUALITIES[number];
+export declare const RESOLUTIONS: readonly ["1k", "2k", "4k"];
+export type Resolution = typeof RESOLUTIONS[number];
+export declare const ASPECT_RATIOS: readonly ["auto", "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"];
+export type AspectRatio = typeof ASPECT_RATIOS[number];

package/dist/image-models/types.js

@@ -0,0 +1,26 @@
+/**
+ * Canonical image-model vocabulary for the Imagen service contract — the
+ * aspect-ratio / resolution / quality unions defined exactly once and shared by
+ * every consumer (the Imagen service and its SDK clients).
+ *
+ * `quality` is deliberately three tiers — `auto` was dropped at the product
+ * layer (callers should pick a concrete tier before submitting work to Imagen).
+ * A consumer's database may keep a legacy `auto` enum value for historical rows,
+ * but nothing new is written with it.
+ */
+export const IMAGE_MODEL_IDS = ['openai/gpt-image-2'];
+export const IMAGE_QUALITIES = ['low', 'medium', 'high'];
+export const RESOLUTIONS = ['1k', '2k', '4k'];
+export const ASPECT_RATIOS = [
+    'auto',
+    '1:1',
+    '2:3',
+    '3:2',
+    '3:4',
+    '4:3',
+    '4:5',
+    '5:4',
+    '9:16',
+    '16:9',
+    '21:9',
+];

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './callback.js';
+export * from './client.js';
+export * from './contracts.js';
+export * from './image-models/index.js';
+export * from './service-jwt.js';
+export * from './stable-hash.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from './callback.js';
+export * from './client.js';
+export * from './contracts.js';
+export * from './image-models/index.js';
+export * from './service-jwt.js';
+export * from './stable-hash.js';

package/dist/service-jwt.d.ts

@@ -0,0 +1,31 @@
+import type { JWTPayload } from 'jose';
+/**
+ * Identity of the service that calls Imagen. Imagen is generic infrastructure;
+ * the caller's name is configurable. `tutu` is the default because it is the
+ * first consumer, but any client can set its own name via `SERVICE_CLIENT_NAME`.
+ */
+export declare const DEFAULT_SERVICE_CLIENT_NAME = "tutu";
+export declare class ServiceJwtError extends Error {
+    constructor(message?: string);
+}
+export interface SignServiceJwtInput {
+    secret: string;
+    issuer: string;
+    audience: string;
+    subject: string;
+    expiresInSeconds?: number;
+}
+export interface VerifyServiceJwtInput {
+    token: string;
+    secret: string;
+    issuer: string;
+    audience: string;
+    subject?: string;
+    maxTtlSeconds?: number;
+}
+export declare function signServiceJwt({ secret, issuer, audience, subject, expiresInSeconds, }: SignServiceJwtInput): Promise<string>;
+export declare function signClientToImagenJwt(secret: string, clientName?: string): Promise<string>;
+export declare function signImagenToClientJwt(secret: string, clientName?: string): Promise<string>;
+export declare function verifyServiceJwt({ token, secret, issuer, audience, subject, maxTtlSeconds, }: VerifyServiceJwtInput): Promise<JWTPayload>;
+export declare function verifyClientToImagenJwt(token: string, secret: string, clientName?: string): Promise<JWTPayload>;
+export declare function verifyImagenCallbackJwt(token: string, secret: string, clientName?: string): Promise<JWTPayload>;

package/dist/service-jwt.js

@@ -0,0 +1,93 @@
+import { jwtVerify, SignJWT } from 'jose';
+const DEFAULT_MAX_TTL_SECONDS = 5 * 60;
+const CLOCK_TOLERANCE_SECONDS = 5;
+/**
+ * Identity of the service that calls Imagen. Imagen is generic infrastructure;
+ * the caller's name is configurable. `tutu` is the default because it is the
+ * first consumer, but any client can set its own name via `SERVICE_CLIENT_NAME`.
+ */
+export const DEFAULT_SERVICE_CLIENT_NAME = 'tutu';
+export class ServiceJwtError extends Error {
+    constructor(message = 'Invalid service token') {
+        super(message);
+        this.name = 'ServiceJwtError';
+    }
+}
+function secretKey(secret) {
+    return new TextEncoder().encode(secret);
+}
+function assertSecret(secret) {
+    if (secret.length < 32)
+        throw new ServiceJwtError('SERVICE_JWT_SECRET must be at least 32 characters');
+}
+export async function signServiceJwt({ secret, issuer, audience, subject, expiresInSeconds = DEFAULT_MAX_TTL_SECONDS, }) {
+    assertSecret(secret);
+    if (expiresInSeconds > DEFAULT_MAX_TTL_SECONDS)
+        throw new ServiceJwtError('service token ttl must not exceed 5 minutes');
+    return new SignJWT({})
+        .setProtectedHeader({ alg: 'HS256', typ: 'JWT' })
+        .setIssuer(issuer)
+        .setAudience(audience)
+        .setSubject(subject)
+        .setIssuedAt()
+        .setExpirationTime(`${expiresInSeconds}s`)
+        .sign(secretKey(secret));
+}
+export function signClientToImagenJwt(secret, clientName = DEFAULT_SERVICE_CLIENT_NAME) {
+    return signServiceJwt({
+        secret,
+        issuer: clientName,
+        audience: 'imagen',
+        subject: `service:${clientName}`,
+    });
+}
+export function signImagenToClientJwt(secret, clientName = DEFAULT_SERVICE_CLIENT_NAME) {
+    return signServiceJwt({
+        secret,
+        issuer: 'imagen',
+        audience: clientName,
+        subject: 'service:imagen',
+    });
+}
+export async function verifyServiceJwt({ token, secret, issuer, audience, subject, maxTtlSeconds = DEFAULT_MAX_TTL_SECONDS, }) {
+    try {
+        assertSecret(secret);
+        const { payload } = await jwtVerify(token, secretKey(secret), {
+            issuer,
+            audience,
+            algorithms: ['HS256'],
+            clockTolerance: CLOCK_TOLERANCE_SECONDS,
+        });
+        if (subject && payload.sub !== subject)
+            throw new ServiceJwtError('service token subject mismatch');
+        if (payload.exp && payload.iat) {
+            const ttl = payload.exp - payload.iat;
+            if (ttl > maxTtlSeconds + CLOCK_TOLERANCE_SECONDS)
+                throw new ServiceJwtError('service token ttl is too long');
+        }
+        return payload;
+    }
+    catch (error) {
+        if (error instanceof ServiceJwtError)
+            throw error;
+        throw new ServiceJwtError();
+    }
+}
+export async function verifyClientToImagenJwt(token, secret, clientName = DEFAULT_SERVICE_CLIENT_NAME) {
+    return verifyServiceJwt({
+        token,
+        secret,
+        issuer: clientName,
+        audience: 'imagen',
+        subject: `service:${clientName}`,
+    });
+}
+export async function verifyImagenCallbackJwt(token, secret, clientName = DEFAULT_SERVICE_CLIENT_NAME) {
+    return verifyServiceJwt({
+        token,
+        secret,
+        issuer: 'imagen',
+        audience: clientName,
+        subject: 'service:imagen',
+    });
+}

package/dist/stable-hash.d.ts

@@ -0,0 +1,2 @@
+export declare function stableStringify(value: unknown): string;
+export declare function sha256StableHash(value: unknown): string;

package/dist/stable-hash.js

@@ -0,0 +1,18 @@
+import { createHash } from 'node:crypto';
+function normalize(value) {
+    if (Array.isArray(value))
+        return value.map(normalize);
+    if (value && typeof value === 'object') {
+        const record = value;
+        return Object.fromEntries(Object.keys(record)
+            .sort()
+            .map(key => [key, normalize(record[key])]));
+    }
+    return value;
+}
+export function stableStringify(value) {
+    return JSON.stringify(normalize(value));
+}
+export function sha256StableHash(value) {
+    return createHash('sha256').update(stableStringify(value)).digest('hex');
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@donotlb/imagen-sdk",
+  "type": "module",
+  "version": "0.2.0",
+  "private": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./image-models": {
+      "types": "./dist/image-models/index.d.ts",
+      "default": "./dist/image-models/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "jose": "^6.2.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.4",
+    "typescript": "~5.9.3",
+    "vitest": "~4.1.8",
+    "@pi/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}