@distinctagency/cms-client 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,419 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+
+/** Field types supported by the CMS schema */
+type FieldType = "text" | "textarea" | "richtext" | "date" | "datetime" | "select" | "number" | "boolean" | "image" | "gallery" | "url" | "reference" | "computed" | "color" | "tags" | "json";
+interface ImageConfig {
+    max_width?: number;
+    max_height?: number;
+    aspect_ratio?: string;
+    aspect_tolerance?: number;
+    long_edge?: number;
+}
+/** A single field definition within a content type schema */
+interface FieldDefinition {
+    name: string;
+    type: FieldType;
+    label: string;
+    required?: boolean;
+    options?: string[];
+    default?: string | number | boolean;
+    /** For reference fields: the slug of the collection to reference */
+    reference_to?: string;
+    /** For computed fields: the computation config */
+    compute?: {
+        function: "read_time" | "word_count" | "char_count" | "excerpt_auto" | "seo_score";
+        source_field: string;
+    };
+    /** For image/gallery fields: processing constraints */
+    image_config?: ImageConfig;
+}
+interface Tenant {
+    id: string;
+    name: string;
+    slug: string;
+    domain: string | null;
+    staging_domain: string | null;
+    api_key: string;
+    created_at: string;
+}
+interface CmsClientOptions {
+    /** Tenant API key (UUID) — required for authentication */
+    apiKey: string;
+    /** CMS app URL for API calls (e.g. orders) */
+    appUrl?: string;
+}
+interface Profile {
+    id: string;
+    tenant_id: string;
+    full_name: string | null;
+    role: "super_admin" | "admin" | "editor";
+    created_at: string;
+}
+interface ContentTypeSeoConfig {
+    enabled: boolean;
+    /** Field mappings — which schema fields serve which SEO purpose */
+    field_map: {
+        /** Primary body content field (for word count, headings, links, images) */
+        content?: string;
+        /** Featured/hero image field */
+        featured_image?: string;
+        /** SEO title override field (falls back to standard title) */
+        seo_title?: string;
+        /** Meta description field (falls back to standard excerpt) */
+        seo_description?: string;
+        /** Author/byline field */
+        author?: string;
+        /** Published date field */
+        publish_date?: string;
+        /** Category or tag field */
+        category?: string;
+        /** Canonical URL field */
+        canonical_url?: string;
+    };
+}
+interface ContentType {
+    id: string;
+    tenant_id: string;
+    name: string;
+    slug: string;
+    schema: FieldDefinition[];
+    seo_config?: ContentTypeSeoConfig | null;
+    created_at: string;
+}
+interface ContentItem {
+    id: string;
+    tenant_id: string;
+    content_type_id: string;
+    title: string;
+    slug: string;
+    status: "draft" | "published" | "archived" | "pending_review";
+    published_at: string | null;
+    seo_title: string | null;
+    seo_description: string | null;
+    og_image: string | null;
+    featured_image: string | null;
+    excerpt: string | null;
+    sort_order: number;
+    data: Record<string, unknown>;
+    created_by: string | null;
+    created_at: string;
+    updated_at: string;
+    /** Joined content type (included when queried with select) */
+    content_type?: ContentType;
+}
+interface MediaItem {
+    id: string;
+    tenant_id: string;
+    url: string;
+    filename: string;
+    alt_text: string | null;
+    mime_type: string | null;
+    size: number | null;
+    created_by: string | null;
+    created_at: string;
+}
+interface TenantMembership {
+    id: string;
+    user_id: string;
+    tenant_id: string;
+    role: "admin" | "editor";
+    created_at: string;
+    tenant?: Tenant;
+}
+interface ContentQueryOptions {
+    status?: "draft" | "published" | "archived" | "pending_review";
+    orderBy?: string;
+    orderDirection?: "asc" | "desc";
+    limit?: number;
+    offset?: number;
+}
+interface Product {
+    id: string;
+    tenant_id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    short_description: string | null;
+    status: "draft" | "published" | "archived";
+    price_cents: number;
+    compare_at_price_cents: number | null;
+    sku: string | null;
+    barcode: string | null;
+    featured_image: string | null;
+    gallery: string[];
+    category: string | null;
+    tags: string[];
+    weight_grams: number | null;
+    is_digital: boolean;
+    track_inventory: boolean;
+    allow_overselling: boolean;
+    seo_title: string | null;
+    seo_description: string | null;
+    metadata: Record<string, unknown>;
+    sort_order: number;
+    published_at: string | null;
+    created_at: string;
+    updated_at: string;
+    variants?: ProductVariant[];
+    options?: ProductOption[];
+}
+interface ProductVariant {
+    id: string;
+    product_id: string;
+    name: string;
+    sku: string | null;
+    price_cents: number | null;
+    option_values: Record<string, string>;
+    stock_quantity: number;
+    low_stock_threshold: number;
+    weight_grams: number | null;
+    image_url: string | null;
+    is_active: boolean;
+    sort_order: number;
+}
+interface ProductOption {
+    id: string;
+    product_id: string;
+    name: string;
+    values: string[];
+    sort_order: number;
+}
+interface OrderAddress {
+    line1: string;
+    line2?: string;
+    city: string;
+    region: string;
+    postcode: string;
+    country: string;
+}
+interface CreateOrderParams {
+    customer_email: string;
+    customer_name?: string;
+    customer_phone?: string;
+    line_items: {
+        product_id: string;
+        variant_id?: string;
+        quantity: number;
+    }[];
+    shipping_address?: OrderAddress;
+    billing_address?: OrderAddress;
+    shipping_method?: string;
+    discount_code?: string;
+}
+interface CreateOrderResult {
+    order_id: string;
+    order_number: string;
+    client_secret: string;
+    total_cents: number;
+    currency: string;
+}
+interface ProductQueryOptions {
+    category?: string;
+    tags?: string[];
+    limit?: number;
+    offset?: number;
+    sort?: "name" | "price_cents" | "created_at" | "sort_order";
+    order?: "asc" | "desc";
+}
+
+/**
+ * Creates a CMS query client authenticated with a tenant API key.
+ *
+ * Usage:
+ * ```ts
+ * const cms = createCmsClient(supabase, { apiKey: process.env.CMS_API_KEY! })
+ * const events = await cms.getContentItems('events', { status: 'published' })
+ * ```
+ *
+ * The API key is sent as an `x-cms-api-key` header on every request.
+ * Supabase RLS policies validate it against the tenant's stored key.
+ */
+declare function createCmsClient(supabase: SupabaseClient, options: CmsClientOptions): {
+    /**
+     * List content items for a content type.
+     * Defaults to published items ordered by most recent.
+     */
+    getContentItems(contentTypeSlug: string, options?: ContentQueryOptions): Promise<ContentItem[]>;
+    /**
+     * Get a single content item by its slug.
+     * Returns null if not found.
+     */
+    getContentItemBySlug(contentTypeSlug: string, itemSlug: string): Promise<ContentItem | null>;
+    /**
+     * Get a content type definition (including its field schema).
+     */
+    getContentType(contentTypeSlug: string): Promise<ContentType>;
+    /**
+     * Get all slugs for a content type (for generateStaticParams).
+     */
+    getAllSlugs(contentTypeSlug: string): Promise<{
+        slug: string;
+    }[]>;
+    /**
+     * List all content types for this tenant.
+     */
+    getContentTypes(): Promise<ContentType[]>;
+    /**
+     * Get all slug redirects for a content type.
+     * Use in next.config.js redirects() or middleware for 301s.
+     * Returns: [{ old_slug, new_slug }, ...]
+     */
+    getRedirects(contentTypeSlug: string): Promise<{
+        old_slug: string;
+        new_slug: string;
+    }[]>;
+    /**
+     * Get all custom path redirects for this tenant.
+     * Use alongside getRedirects() in next.config.ts for full redirect coverage.
+     */
+    getCustomRedirects(): Promise<{
+        source_path: string;
+        destination_path: string;
+        permanent: boolean;
+    }[]>;
+    /**
+     * Get form submissions for a specific form.
+     * Useful for displaying testimonials, reviews, etc.
+     */
+    getFormSubmissions(formSlug: string, options?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<Record<string, unknown>[]>;
+    /**
+     * Get a form configuration by slug.
+     */
+    getForm(formSlug: string): Promise<Record<string, unknown> | null>;
+};
+
+declare function createShopClient(supabase: SupabaseClient, options: {
+    apiKey: string;
+    appUrl?: string;
+}): {
+    getProducts(queryOptions?: ProductQueryOptions): Promise<Product[]>;
+    getProductBySlug(slug: string): Promise<Product | null>;
+    getProductCategories(): Promise<string[]>;
+    createOrder(params: CreateOrderParams): Promise<CreateOrderResult>;
+};
+
+interface CmsAnalyticsProps {
+    /** The CMS tracking endpoint URL */
+    trackingUrl?: string;
+    /** Tenant API key */
+    apiKey: string;
+    /** Content item ID (from CMS) */
+    contentItemId?: string;
+    /** Content type slug (e.g. "blog_posts") */
+    contentTypeSlug: string;
+    /** Item slug (e.g. "my-post") */
+    itemSlug: string;
+    /** Enable scroll depth tracking (default: true) */
+    trackScroll?: boolean;
+    /** Enable time-on-page tracking (default: true) */
+    trackTime?: boolean;
+}
+/**
+ * Drop-in analytics component for CMS content pages.
+ * Tracks page views, scroll depth, and time on page.
+ *
+ * Usage:
+ * ```tsx
+ * <CmsAnalytics
+ *   apiKey={process.env.NEXT_PUBLIC_CMS_API_KEY!}
+ *   contentTypeSlug="blog_posts"
+ *   itemSlug={params.slug}
+ * />
+ * ```
+ */
+declare function CmsAnalytics({ trackingUrl, apiKey, contentItemId, contentTypeSlug, itemSlug, trackScroll, trackTime, }: CmsAnalyticsProps): null;
+
+interface PageTrackerProps {
+    /** The CMS tracking endpoint URL */
+    trackingUrl?: string;
+    /** Tenant API key */
+    apiKey: string;
+    /** Enable scroll depth tracking (default: true) */
+    trackScroll?: boolean;
+    /** Enable time-on-page tracking (default: true) */
+    trackTime?: boolean;
+}
+/**
+ * Site-wide page tracker. Add once in root layout to track all pages.
+ * Automatically detects CMS content pages from URL structure.
+ *
+ * Usage in src/app/layout.tsx:
+ * ```tsx
+ * import { PageTracker } from "@distinct-cms/client"
+ *
+ * <body>
+ *   {children}
+ *   <PageTracker apiKey={process.env.NEXT_PUBLIC_CMS_API_KEY!} />
+ * </body>
+ * ```
+ */
+declare function PageTracker({ trackingUrl, apiKey, trackScroll, trackTime, }: PageTrackerProps): null;
+
+/**
+ * CDN image transform helpers using Supabase Storage's built-in image transformation.
+ *
+ * Converts /object/public/ URLs to /render/image/public/ with transform params.
+ * Works both server-side and client-side (no Node.js-only APIs).
+ */
+interface ImageTransformOptions {
+    width?: number;
+    height?: number;
+    quality?: number;
+    resize?: "contain" | "cover" | "fill";
+    format?: "origin";
+}
+/**
+ * Transform a Supabase Storage URL to use Supabase's image transformation.
+ * Converts /object/public/ URLs to /render/image/public/ with transform params.
+ */
+declare function getTransformUrl(originalUrl: string, options?: ImageTransformOptions): string;
+/**
+ * Generate a srcSet string for responsive images.
+ */
+declare function getSrcSet(originalUrl: string, widths?: number[], quality?: number): string;
+/**
+ * Generate common image sizes for different use cases.
+ */
+declare const IMAGE_PRESETS: {
+    readonly thumbnail: {
+        readonly width: 150;
+        readonly height: 150;
+        readonly resize: "cover";
+        readonly quality: 70;
+    };
+    readonly card: {
+        readonly width: 400;
+        readonly height: 300;
+        readonly resize: "cover";
+        readonly quality: 80;
+    };
+    readonly hero: {
+        readonly width: 1200;
+        readonly height: 630;
+        readonly resize: "cover";
+        readonly quality: 85;
+    };
+    readonly og: {
+        readonly width: 1200;
+        readonly height: 630;
+        readonly resize: "cover";
+        readonly quality: 90;
+    };
+    readonly avatar: {
+        readonly width: 80;
+        readonly height: 80;
+        readonly resize: "cover";
+        readonly quality: 75;
+    };
+    readonly full: {
+        readonly width: 1920;
+        readonly resize: "contain";
+        readonly quality: 85;
+    };
+};
+
+export { CmsAnalytics, type CmsClientOptions, type ContentItem, type ContentQueryOptions, type ContentType, type ContentTypeSeoConfig, type CreateOrderParams, type CreateOrderResult, type FieldDefinition, type FieldType, IMAGE_PRESETS, type ImageConfig, type ImageTransformOptions, type MediaItem, type OrderAddress, PageTracker, type Product, type ProductOption, type ProductQueryOptions, type ProductVariant, type Profile, type Tenant, type TenantMembership, createCmsClient, createShopClient, getSrcSet, getTransformUrl };