@idelio/contracts 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SFER LABS LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,27 @@
+# @idelio/contracts
+
+The shared contract of the [Idelio](https://idelio.pro) API: zod schemas and
+TypeScript types for every request and response, the asset catalogue, and
+credit pricing. `@idelio/sdk` is built on it; install it directly when you
+want to validate payloads yourself - for example an incoming webhook.
+
+## Install
+
+```bash
+npm install @idelio/contracts
+```
+
+Requires Node.js 20.19 or later; the package is ESM-only.
+
+## Usage
+
+```typescript
+import { webhookEnvelopeSchema, type Brand } from "@idelio/contracts";
+import { estimateCredits } from "@idelio/contracts/pricing";
+
+const event = webhookEnvelopeSchema.parse(JSON.parse(rawBody));
+```
+
+## OpenAPI
+
+The OpenAPI 3.1 document is included at `openapi/openapi.yaml`.

package/dist/api-keys.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+export declare const apiKeyEnvironments: readonly ["live", "test"];
+export declare const apiKeySchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    environment: z.ZodEnum<{
+        live: "live";
+        test: "test";
+    }>;
+    prefix: z.ZodString;
+    last4: z.ZodString;
+    requests: z.ZodNumber;
+    credits: z.ZodNumber;
+    created_at: z.ZodString;
+    last_used_at: z.ZodNullable<z.ZodString>;
+    created_by_email: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const apiKeyWithSecretSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    environment: z.ZodEnum<{
+        live: "live";
+        test: "test";
+    }>;
+    prefix: z.ZodString;
+    last4: z.ZodString;
+    requests: z.ZodNumber;
+    credits: z.ZodNumber;
+    created_at: z.ZodString;
+    last_used_at: z.ZodNullable<z.ZodString>;
+    created_by_email: z.ZodNullable<z.ZodString>;
+    secret: z.ZodString;
+}, z.core.$strip>;
+export declare const createApiKeyRequestSchema: z.ZodObject<{
+    name: z.ZodString;
+    environment: z.ZodDefault<z.ZodEnum<{
+        live: "live";
+        test: "test";
+    }>>;
+}, z.core.$strip>;
+export type ApiKeyEnvironment = (typeof apiKeyEnvironments)[number];
+export type ApiKey = z.infer<typeof apiKeySchema>;
+export type ApiKeyWithSecret = z.infer<typeof apiKeyWithSecretSchema>;
+export type CreateApiKeyRequest = z.infer<typeof createApiKeyRequestSchema>;

package/dist/api-keys.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+export const apiKeyEnvironments = ["live", "test"];
+export const apiKeySchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    environment: z.enum(apiKeyEnvironments),
+    prefix: z.string(),
+    last4: z.string(),
+    requests: z.number().int().nonnegative(),
+    credits: z.number().int().nonnegative(),
+    created_at: z.string().datetime(),
+    last_used_at: z.string().datetime().nullable(),
+    created_by_email: z.string().nullable(),
+});
+export const apiKeyWithSecretSchema = apiKeySchema.extend({ secret: z.string() });
+export const createApiKeyRequestSchema = z.object({
+    name: z.string().trim().min(1).max(80),
+    environment: z.enum(apiKeyEnvironments).default("live"),
+});

package/dist/assets.d.ts

@@ -0,0 +1,188 @@
+import { z } from "zod";
+export declare const assetStatuses: readonly ["queued", "generating", "ready", "failed"];
+export declare const qaCheckStatuses: readonly ["pass", "warn", "fail"];
+export declare const qaCheckSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    status: z.ZodEnum<{
+        pass: "pass";
+        warn: "warn";
+        fail: "fail";
+    }>;
+    detail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    source: z.ZodOptional<z.ZodEnum<{
+        ai: "ai";
+        deterministic: "deterministic";
+    }>>;
+}, z.core.$strip>;
+export declare const qaReportSchema: z.ZodObject<{
+    overall_score: z.ZodNumber;
+    checks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        status: z.ZodEnum<{
+            pass: "pass";
+            warn: "warn";
+            fail: "fail";
+        }>;
+        detail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        source: z.ZodOptional<z.ZodEnum<{
+            ai: "ai";
+            deterministic: "deterministic";
+        }>>;
+    }, z.core.$strip>>>;
+}, z.core.$catchall<z.ZodUnknown>>;
+export type QaCheckStatus = (typeof qaCheckStatuses)[number];
+export type QaCheck = z.infer<typeof qaCheckSchema>;
+export type QaReport = z.infer<typeof qaReportSchema>;
+export declare const assetSchema: z.ZodObject<{
+    id: z.ZodString;
+    brand_id: z.ZodString;
+    version_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodEnum<{
+        logo: "logo";
+        logo_alternative: "logo_alternative";
+        logo_wordmark: "logo_wordmark";
+        color_palette: "color_palette";
+        font_pairing: "font_pairing";
+        logo_mono: "logo_mono";
+        logo_reversed: "logo_reversed";
+        favicon: "favicon";
+        brand_guide: "brand_guide";
+        profile_avatar: "profile_avatar";
+        social_x: "social_x";
+        social_linkedin: "social_linkedin";
+        social_linkedin_personal: "social_linkedin_personal";
+        social_facebook: "social_facebook";
+        social_youtube: "social_youtube";
+        social_post: "social_post";
+        social_story: "social_story";
+        app_icon: "app_icon";
+        og_image: "og_image";
+        email_signature: "email_signature";
+        hero_image: "hero_image";
+        play_feature_graphic: "play_feature_graphic";
+        business_card: "business_card";
+        letterhead: "letterhead";
+        mockup: "mockup";
+        custom_image: "custom_image";
+    }>;
+    name: z.ZodString;
+    status: z.ZodEnum<{
+        generating: "generating";
+        ready: "ready";
+        failed: "failed";
+        queued: "queued";
+    }>;
+    url: z.ZodNullable<z.ZodString>;
+    thumbnail_url: z.ZodNullable<z.ZodString>;
+    credits: z.ZodNumber;
+    pixel_check: z.ZodNullable<z.ZodNumber>;
+    qa_report: z.ZodNullable<z.ZodObject<{
+        overall_score: z.ZodNumber;
+        checks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            status: z.ZodEnum<{
+                pass: "pass";
+                warn: "warn";
+                fail: "fail";
+            }>;
+            detail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            source: z.ZodOptional<z.ZodEnum<{
+                ai: "ai";
+                deterministic: "deterministic";
+            }>>;
+        }, z.core.$strip>>>;
+    }, z.core.$catchall<z.ZodUnknown>>>;
+    formats: z.ZodArray<z.ZodString>;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+export type AssetStatus = (typeof assetStatuses)[number];
+export type Asset = z.infer<typeof assetSchema>;
+export declare const assetVersionSchema: z.ZodObject<{
+    id: z.ZodString;
+    asset_id: z.ZodString;
+    parent_version_id: z.ZodNullable<z.ZodString>;
+    files: z.ZodArray<z.ZodObject<{
+        format: z.ZodString;
+        content_hash: z.ZodString;
+        storage_key: z.ZodString;
+        bytes: z.ZodNumber;
+    }, z.core.$strip>>;
+    credit_cost: z.ZodNumber;
+    qa_report: z.ZodNullable<z.ZodObject<{
+        overall_score: z.ZodNumber;
+        checks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            status: z.ZodEnum<{
+                pass: "pass";
+                warn: "warn";
+                fail: "fail";
+            }>;
+            detail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            source: z.ZodOptional<z.ZodEnum<{
+                ai: "ai";
+                deterministic: "deterministic";
+            }>>;
+        }, z.core.$strip>>>;
+    }, z.core.$catchall<z.ZodUnknown>>>;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+export type AssetVersion = z.infer<typeof assetVersionSchema>;
+export declare const wordmarkStyleCount = 11;
+export declare const wordmarkStyleIndexSchema: z.ZodNumber;
+export declare const logoTreatmentOverridesSchema: z.ZodObject<{
+    family: z.ZodOptional<z.ZodString>;
+    ink: z.ZodOptional<z.ZodString>;
+    accent: z.ZodOptional<z.ZodString>;
+    styleSeed: z.ZodOptional<z.ZodString>;
+    styleIndex: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type LogoTreatmentOverrides = z.infer<typeof logoTreatmentOverridesSchema>;
+export declare const refineRequestSchema: z.ZodUnion<readonly [z.ZodObject<{
+    instruction: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    family: z.ZodOptional<z.ZodString>;
+    ink: z.ZodOptional<z.ZodString>;
+    accent: z.ZodOptional<z.ZodString>;
+    styleSeed: z.ZodOptional<z.ZodString>;
+    styleIndex: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>]>;
+export type RefineRequest = z.infer<typeof refineRequestSchema>;
+export declare const logoTreatmentSchema: z.ZodObject<{
+    family: z.ZodString;
+    ink: z.ZodString;
+    accent: z.ZodString;
+    style_seed: z.ZodString;
+    style_index: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type LogoTreatment = z.infer<typeof logoTreatmentSchema>;
+export declare const logoTreatmentPreviewQuerySchema: z.ZodObject<{
+    family: z.ZodOptional<z.ZodString>;
+    ink: z.ZodOptional<z.ZodString>;
+    accent: z.ZodOptional<z.ZodString>;
+    style_seed: z.ZodOptional<z.ZodString>;
+    style_index: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type LogoTreatmentPreviewQuery = z.infer<typeof logoTreatmentPreviewQuerySchema>;
+export declare const logoVariationPresets: readonly ["more_minimal", "more_startup", "bolder", "playful", "elegant", "geometric", "hand_drawn", "monochrome"];
+export type LogoVariationPreset = (typeof logoVariationPresets)[number];
+export declare const variationRequestSchema: z.ZodObject<{
+    preset: z.ZodEnum<{
+        playful: "playful";
+        elegant: "elegant";
+        geometric: "geometric";
+        more_minimal: "more_minimal";
+        more_startup: "more_startup";
+        bolder: "bolder";
+        hand_drawn: "hand_drawn";
+        monochrome: "monochrome";
+    }>;
+}, z.core.$strip>;
+export type VariationRequest = z.infer<typeof variationRequestSchema>;
+export declare const restoreRequestSchema: z.ZodObject<{
+    to_version: z.ZodString;
+}, z.core.$strip>;
+export type RestoreRequest = z.infer<typeof restoreRequestSchema>;

package/dist/assets.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { assetKinds } from "./brands.js";
+import { hexColorSchema } from "./creative-direction.js";
+export const assetStatuses = ["queued", "generating", "ready", "failed"];
+export const qaCheckStatuses = ["pass", "warn", "fail"];
+export const qaCheckSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    status: z.enum(qaCheckStatuses),
+    detail: z.string().nullable().optional(),
+    source: z.enum(["deterministic", "ai"]).optional(),
+});
+export const qaReportSchema = z
+    .object({
+    overall_score: z.number().int().min(0).max(100),
+    checks: z.array(qaCheckSchema).optional(),
+})
+    .catchall(z.unknown());
+export const assetSchema = z.object({
+    id: z.string(),
+    brand_id: z.string(),
+    version_id: z.string().nullable(),
+    kind: z.enum(assetKinds),
+    name: z.string(),
+    status: z.enum(assetStatuses),
+    url: z.string().nullable(),
+    thumbnail_url: z.string().nullable(),
+    credits: z.number().int(),
+    pixel_check: z.number().int().nullable(),
+    qa_report: qaReportSchema.nullable(),
+    formats: z.array(z.string()),
+    created_at: z.string().datetime(),
+});
+export const assetVersionSchema = z.object({
+    id: z.string(),
+    asset_id: z.string(),
+    parent_version_id: z.string().nullable(),
+    files: z.array(z.object({
+        format: z.string(),
+        content_hash: z.string(),
+        storage_key: z.string(),
+        bytes: z.number().int(),
+    })),
+    credit_cost: z.number().int(),
+    qa_report: qaReportSchema.nullable(),
+    created_at: z.string().datetime(),
+});
+export const wordmarkStyleCount = 11;
+export const wordmarkStyleIndexSchema = z
+    .number()
+    .int()
+    .min(0)
+    .max(wordmarkStyleCount - 1);
+export const logoTreatmentOverridesSchema = z
+    .object({
+    family: z.string().min(1).max(200).optional(),
+    ink: hexColorSchema.optional(),
+    accent: hexColorSchema.optional(),
+    styleSeed: z.string().min(1).max(64).optional(),
+    styleIndex: wordmarkStyleIndexSchema.optional(),
+})
+    .refine((v) => v.family !== undefined ||
+    v.ink !== undefined ||
+    v.accent !== undefined ||
+    v.styleSeed !== undefined ||
+    v.styleIndex !== undefined, {
+    message: "At least one of family, ink, accent, styleIndex, or styleSeed is required.",
+});
+export const refineRequestSchema = z.union([
+    z.object({ instruction: z.string().min(1).max(500) }),
+    logoTreatmentOverridesSchema,
+]);
+export const logoTreatmentSchema = z.object({
+    family: z.string(),
+    ink: hexColorSchema,
+    accent: hexColorSchema,
+    style_seed: z.string(),
+    style_index: wordmarkStyleIndexSchema.nullable(),
+});
+export const logoTreatmentPreviewQuerySchema = z.object({
+    family: z.string().min(1).max(200).optional(),
+    ink: hexColorSchema.optional(),
+    accent: hexColorSchema.optional(),
+    style_seed: z.string().min(1).max(64).optional(),
+    style_index: z.coerce
+        .number()
+        .int()
+        .min(0)
+        .max(wordmarkStyleCount - 1)
+        .optional(),
+});
+export const logoVariationPresets = [
+    "more_minimal",
+    "more_startup",
+    "bolder",
+    "playful",
+    "elegant",
+    "geometric",
+    "hand_drawn",
+    "monochrome",
+];
+export const variationRequestSchema = z.object({
+    preset: z.enum(logoVariationPresets),
+});
+export const restoreRequestSchema = z.object({
+    to_version: z.string().min(1),
+});

package/dist/billing.d.ts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+export declare const subscriptionSchema: z.ZodObject<{
+    plan: z.ZodEnum<{
+        studio: "studio";
+        free: "free";
+        pro: "pro";
+        agency: "agency";
+    }>;
+    status: z.ZodNullable<z.ZodString>;
+    next_billed_at: z.ZodNullable<z.ZodString>;
+    cancel_at_period_end: z.ZodBoolean;
+    pending_plan: z.ZodNullable<z.ZodEnum<{
+        studio: "studio";
+        free: "free";
+        pro: "pro";
+        agency: "agency";
+    }>>;
+    plan_change_effective_at: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type Subscription = z.infer<typeof subscriptionSchema>;
+export declare const checkoutRequestSchema: z.ZodObject<{
+    price_id: z.ZodString;
+    success_url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CheckoutRequest = z.infer<typeof checkoutRequestSchema>;
+export declare const changePlanRequestSchema: z.ZodObject<{
+    price_id: z.ZodString;
+}, z.core.$strip>;
+export type ChangePlanRequest = z.infer<typeof changePlanRequestSchema>;
+export declare const billingCatalogSchema: z.ZodObject<{
+    plans: z.ZodObject<{
+        pro: z.ZodNullable<z.ZodString>;
+        studio: z.ZodNullable<z.ZodString>;
+        agency: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    topups: z.ZodObject<{
+        "100": z.ZodNullable<z.ZodString>;
+        "300": z.ZodNullable<z.ZodString>;
+        "1000": z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type BillingCatalog = z.infer<typeof billingCatalogSchema>;
+export declare const autoTopupSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    pack_credits: z.ZodNullable<z.ZodUnion<readonly [z.ZodLiteral<100>, z.ZodLiteral<300>, z.ZodLiteral<1000>]>>;
+}, z.core.$strip>;
+export type AutoTopup = z.infer<typeof autoTopupSchema>;
+export declare const updateAutoTopupRequestSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    pack_credits: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<100>, z.ZodLiteral<300>, z.ZodLiteral<1000>]>>;
+}, z.core.$strip>;
+export type UpdateAutoTopupRequest = z.infer<typeof updateAutoTopupRequestSchema>;
+export declare const paymentMethodSchema: z.ZodObject<{
+    brand: z.ZodString;
+    last4: z.ZodString;
+    exp_month: z.ZodNumber;
+    exp_year: z.ZodNumber;
+}, z.core.$strip>;
+export type PaymentMethod = z.infer<typeof paymentMethodSchema>;
+export declare const invoiceSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodString;
+    total: z.ZodNullable<z.ZodString>;
+    currency: z.ZodNullable<z.ZodString>;
+    billed_at: z.ZodNullable<z.ZodString>;
+    invoice_number: z.ZodNullable<z.ZodString>;
+    url: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type Invoice = z.infer<typeof invoiceSchema>;
+export declare const checkoutSessionSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        pending: "pending";
+        paid: "paid";
+        cancelled: "cancelled";
+    }>;
+    kind: z.ZodEnum<{
+        plan: "plan";
+        topup: "topup";
+    }>;
+    plan: z.ZodNullable<z.ZodEnum<{
+        studio: "studio";
+        free: "free";
+        pro: "pro";
+        agency: "agency";
+    }>>;
+    credits: z.ZodNullable<z.ZodNumber>;
+    amount: z.ZodNullable<z.ZodString>;
+    currency: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+    settled_at: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type CheckoutSession = z.infer<typeof checkoutSessionSchema>;

package/dist/billing.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+export const subscriptionSchema = z.object({
+    plan: z.enum(["free", "pro", "studio", "agency"]),
+    status: z.string().nullable(),
+    next_billed_at: z.string().datetime().nullable(),
+    cancel_at_period_end: z.boolean(),
+    pending_plan: z.enum(["free", "pro", "studio", "agency"]).nullable(),
+    plan_change_effective_at: z.string().datetime().nullable(),
+});
+export const checkoutRequestSchema = z.object({
+    price_id: z.string().min(1),
+    success_url: z.string().url().optional(),
+});
+export const changePlanRequestSchema = z.object({
+    price_id: z.string().min(1),
+});
+export const billingCatalogSchema = z.object({
+    plans: z.object({
+        pro: z.string().nullable(),
+        studio: z.string().nullable(),
+        agency: z.string().nullable(),
+    }),
+    topups: z.object({
+        "100": z.string().nullable(),
+        "300": z.string().nullable(),
+        "1000": z.string().nullable(),
+    }),
+});
+export const autoTopupSchema = z.object({
+    enabled: z.boolean(),
+    pack_credits: z.union([z.literal(100), z.literal(300), z.literal(1000)]).nullable(),
+});
+export const updateAutoTopupRequestSchema = z
+    .object({
+    enabled: z.boolean(),
+    pack_credits: z.union([z.literal(100), z.literal(300), z.literal(1000)]).optional(),
+})
+    .refine((v) => !v.enabled || v.pack_credits !== undefined, {
+    message: "pack_credits is required when enabling auto top-up.",
+    path: ["pack_credits"],
+});
+export const paymentMethodSchema = z.object({
+    brand: z.string(),
+    last4: z.string(),
+    exp_month: z.number().int().min(1).max(12),
+    exp_year: z.number().int(),
+});
+export const invoiceSchema = z.object({
+    id: z.string(),
+    status: z.string(),
+    total: z.string().nullable(),
+    currency: z.string().nullable(),
+    billed_at: z.string().datetime().nullable(),
+    invoice_number: z.string().nullable(),
+    url: z.string().url().nullable(),
+});
+export const checkoutSessionSchema = z.object({
+    id: z.string(),
+    status: z.enum(["pending", "paid", "failed", "cancelled"]),
+    kind: z.enum(["plan", "topup"]),
+    plan: z.enum(["free", "pro", "studio", "agency"]).nullable(),
+    credits: z.number().int().nullable(),
+    amount: z.string().nullable(),
+    currency: z.string().nullable(),
+    created_at: z.string().datetime(),
+    settled_at: z.string().datetime().nullable(),
+});