@playcademy/sdk 0.1.12 → 0.1.14

package/dist/index.d.ts

@@ -225,6 +225,23 @@ type GameMetadata = {
     emoji?: string;
     [key: string]: unknown;
 };
+/**
+ * DNS validation records for custom hostname
+ * Structure for the validationRecords JSON field in game_custom_hostnames table
+ */
+type CustomHostnameValidationRecords = {
+    /** TXT record for ownership verification */
+    ownership?: {
+        name?: string;
+        value?: string;
+        type?: string;
+    };
+    /** TXT records for SSL certificate validation */
+    ssl?: Array<{
+        txt_name?: string;
+        txt_value?: string;
+    }>;
+};
 declare const games: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "games";
     schema: undefined;
@@ -337,8 +354,8 @@ declare const games: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        assetBundleBase: drizzle_orm_pg_core.PgColumn<{
-            name: "asset_bundle_base";
+        deploymentUrl: drizzle_orm_pg_core.PgColumn<{
+            name: "deployment_url";
             tableName: "games";
             dataType: "string";
             columnType: "PgText";
@@ -461,6 +478,207 @@ declare const games: drizzle_orm_pg_core.PgTableWithColumns<{
     };
     dialect: "pg";
 }>;
+/**
+ * Custom hostnames table
+ *
+ * Stores custom domain mappings for games with SSL provisioning via Cloudflare.
+ */
+declare const gameCustomHostnames: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "game_custom_hostnames";
+    schema: undefined;
+    columns: {
+        id: drizzle_orm_pg_core.PgColumn<{
+            name: "id";
+            tableName: "game_custom_hostnames";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        gameId: drizzle_orm_pg_core.PgColumn<{
+            name: "game_id";
+            tableName: "game_custom_hostnames";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        userId: drizzle_orm_pg_core.PgColumn<{
+            name: "user_id";
+            tableName: "game_custom_hostnames";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        hostname: drizzle_orm_pg_core.PgColumn<{
+            name: "hostname";
+            tableName: "game_custom_hostnames";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        cloudflareId: drizzle_orm_pg_core.PgColumn<{
+            name: "cloudflare_id";
+            tableName: "game_custom_hostnames";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        environment: drizzle_orm_pg_core.PgColumn<{
+            name: "environment";
+            tableName: "game_custom_hostnames";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "staging" | "production";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["staging", "production"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: drizzle_orm_pg_core.PgColumn<{
+            name: "status";
+            tableName: "game_custom_hostnames";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "pending" | "pending_validation" | "pending_deployment" | "pending_deletion" | "active" | "blocked" | "deleted";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["pending", "pending_validation", "pending_deployment", "pending_deletion", "active", "blocked", "deleted"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        sslStatus: drizzle_orm_pg_core.PgColumn<{
+            name: "ssl_status";
+            tableName: "game_custom_hostnames";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "pending_validation" | "pending_deployment" | "active" | "deleted" | "initializing" | "pending_issuance";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["initializing", "pending_validation", "pending_issuance", "pending_deployment", "active", "deleted"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        validationRecords: drizzle_orm_pg_core.PgColumn<{
+            name: "validation_records";
+            tableName: "game_custom_hostnames";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: CustomHostnameValidationRecords;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: CustomHostnameValidationRecords;
+        }>;
+        createdAt: drizzle_orm_pg_core.PgColumn<{
+            name: "created_at";
+            tableName: "game_custom_hostnames";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "updated_at";
+            tableName: "game_custom_hostnames";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "items";
     schema: undefined;
@@ -555,7 +773,7 @@ declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "items";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+            data: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -1442,7 +1660,7 @@ declare const characterComponents: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "character_components";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "body" | "outfit" | "hairstyle" | "eyes" | "accessory";
+            data: "accessory" | "body" | "outfit" | "hairstyle" | "eyes";
             driverParam: string;
             notNull: true;
             hasDefault: false;
@@ -2292,66 +2510,32 @@ declare const UpsertGameMetadataSchema: z.ZodEffects<z.ZodObject<{
     mapElementId?: string | null | undefined;
     metadata?: Record<string, unknown> | undefined;
 }>;
+/**
+ * Simplified game manifest for Cloudflare Workers deployments
+ *
+ * The manifest is auto-generated by build tools (Godot plugin, Vite plugin, etc.)
+ * and provides minimal metadata about the build.
+ *
+ * Fields:
+ * - version: Manifest schema version (for future migrations)
+ * - platform: Auto-detected by build tool (e.g., 'web', 'godot@4.3', 'unity@2023')
+ * - createdAt: Build timestamp (ISO 8601)
+ *
+ * Note: With unified Cloudflare Workers deployments, the worker handles all routing
+ * internally, so we no longer need bootMode, entryPoint, or styles fields.
+ */
 declare const ManifestV1Schema: z.ZodObject<{
     version: z.ZodString;
-    bootMode: z.ZodEnum<["iframe", "module"]>;
-    entryPoint: z.ZodEffects<z.ZodString, string, string>;
-    /**
-     * An array of relative paths to CSS stylesheets.
-     * Currently, this property is ONLY utilized by the 'module' boot mode
-     * (`apps/cademy/src/lib/loader/boot-module.ts`) to load external
-     * stylesheets into the game's shadow DOM.
-     *
-     * This property is under review for potential deprecation and removal.
-     * The 'module' boot mode itself has not yet seen significant adoption
-     * or clear use-cases, and if support for module loading is removed in
-     * the future, this 'styles' property would become obsolete.
-     *
-     * If module-based games need styling, alternative approaches might involve
-     * bundling CSS within their JavaScript or managing style injection internally.
-     */
-    styles: z.ZodEffects<z.ZodOptional<z.ZodArray<z.ZodString, "many">>, string[] | undefined, string[] | undefined>;
-    /**
-     * Specifies the game or development platform.
-     * Current values include 'web', 'godot', and 'unity'.
-     * The default in the database is 'web'.
-     *
-     * IMPORTANT: This property is NOT CURRENTLY USED by the core loader
-     * or runtime systems in any functional way. It is present in the manifest
-     * but does not drive any specific behavior in `boot-iframe.ts` or
-     * `boot-module.ts` beyond being a piece of metadata.
-     *
-     * Potential Future Uses (Speculative):
-     * - Analytics: Could be used to gather stats on platform popularity/usage.
-     * - Developer Portal: Might inform UI/UX in the dev portal, e.g., showing
-     *   platform-specific guides or settings.
-     * - Loader Optimizations: In the future, the loader could potentially use this
-     *   to apply platform-specific loading strategies or workarounds, though this
-     *   is unlikely given the current generic boot process.
-     * - Asset Pipeline: Could hint to future asset pipeline tools about expected
-     *   project structures or build artifacts for different platforms.
-     *
-     * The field is intentionally kept somewhat generic. If finer-grained
-     * distinctions are ever needed (e.g., specific web frameworks like 'phaser',
-     * 'three'), this schema might need to be revisited or a separate
-     * 'platformVersion' or 'framework' field could be added.
-     */
-    platform: z.ZodEnum<["web", "godot", "unity"]>;
+    platform: z.ZodString;
     createdAt: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     createdAt: string;
     version: string;
-    platform: "web" | "godot" | "unity";
-    bootMode: "iframe" | "module";
-    entryPoint: string;
-    styles?: string[] | undefined;
+    platform: string;
 }, {
     createdAt: string;
     version: string;
-    platform: "web" | "godot" | "unity";
-    bootMode: "iframe" | "module";
-    entryPoint: string;
-    styles?: string[] | undefined;
+    platform: string;
 }>;
 declare const InsertItemSchema: drizzle_zod.BuildSchema<"insert", {
     id: drizzle_orm_pg_core.PgColumn<{
@@ -2444,7 +2628,7 @@ declare const InsertItemSchema: drizzle_zod.BuildSchema<"insert", {
         tableName: "items";
         dataType: "string";
         columnType: "PgEnumColumn";
-        data: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+        data: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
         driverParam: string;
         notNull: true;
         hasDefault: true;
@@ -2540,21 +2724,21 @@ declare const UpdateItemSchema: z.ZodObject<Omit<{
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     createdAt: z.ZodOptional<z.ZodDate>;
 }, "id" | "createdAt">, "strip", z.ZodTypeAny, {
+    slug?: string | undefined;
     description?: string | null | undefined;
     displayName?: string | undefined;
-    slug?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     gameId?: string | null | undefined;
-    type?: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other" | undefined;
+    type?: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other" | undefined;
     isPlaceable?: boolean | undefined;
     imageUrl?: string | null | undefined;
 }, {
+    slug?: string | undefined;
     description?: string | null | undefined;
     displayName?: string | undefined;
-    slug?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     gameId?: string | null | undefined;
-    type?: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other" | undefined;
+    type?: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other" | undefined;
     isPlaceable?: boolean | undefined;
     imageUrl?: string | null | undefined;
 }>;
@@ -2600,10 +2784,10 @@ declare const InsertShopListingSchema: z.ZodObject<Omit<{
     createdAt: z.ZodOptional<z.ZodDate>;
     updatedAt: z.ZodOptional<z.ZodNullable<z.ZodDate>>;
 }, "id" | "createdAt" | "updatedAt">, "strip", z.ZodTypeAny, {
+    isActive: boolean;
     itemId: string;
     currencyId: string;
     price: number;
-    isActive: boolean;
     sellBackPercentage?: number | null | undefined;
     stock?: number | null | undefined;
     availableFrom?: Date | null | undefined;
@@ -2612,37 +2796,37 @@ declare const InsertShopListingSchema: z.ZodObject<Omit<{
     itemId: string;
     currencyId: string;
     price: number;
+    isActive?: boolean | undefined;
     sellBackPercentage?: number | null | undefined;
     stock?: number | null | undefined;
-    isActive?: boolean | undefined;
     availableFrom?: Date | null | undefined;
     availableUntil?: Date | null | undefined;
 }>;
 declare const UpdateShopListingSchema: z.ZodObject<{
+    isActive: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     itemId: z.ZodOptional<z.ZodString>;
     currencyId: z.ZodOptional<z.ZodString>;
     price: z.ZodOptional<z.ZodNumber>;
     sellBackPercentage: z.ZodOptional<z.ZodNullable<z.ZodOptional<z.ZodNumber>>>;
     stock: z.ZodOptional<z.ZodNullable<z.ZodOptional<z.ZodNumber>>>;
-    isActive: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     availableFrom: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodDate>>>;
     availableUntil: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodDate>>>;
 }, "strip", z.ZodTypeAny, {
+    isActive?: boolean | undefined;
     itemId?: string | undefined;
     currencyId?: string | undefined;
     price?: number | undefined;
     sellBackPercentage?: number | null | undefined;
     stock?: number | null | undefined;
-    isActive?: boolean | undefined;
     availableFrom?: Date | null | undefined;
     availableUntil?: Date | null | undefined;
 }, {
+    isActive?: boolean | undefined;
     itemId?: string | undefined;
     currencyId?: string | undefined;
     price?: number | undefined;
     sellBackPercentage?: number | null | undefined;
     stock?: number | null | undefined;
-    isActive?: boolean | undefined;
     availableFrom?: Date | null | undefined;
     availableUntil?: Date | null | undefined;
 }>;
@@ -2729,31 +2913,21 @@ type PlayerCharacter = typeof playerCharacters.$inferSelect & {
 };
 type PlayerCharacterAccessory = typeof playerCharacterAccessories.$inferSelect;
 type GameRow = typeof games.$inferSelect;
-type BaseGame = Omit<GameRow, 'gameType' | 'assetBundleBase' | 'externalUrl'>;
+type BaseGame = Omit<GameRow, 'gameType' | 'deploymentUrl' | 'externalUrl'>;
 type HostedGame = BaseGame & {
     gameType: 'hosted';
-    assetBundleBase: string;
+    deploymentUrl: string;
     externalUrl: null;
 };
 type ExternalGame = BaseGame & {
     gameType: 'external';
-    assetBundleBase: null;
+    deploymentUrl: null;
     externalUrl: string;
 };
 type Game = HostedGame | ExternalGame;
 type GameStateData = Record<string, unknown>;
+type GameCustomHostname = typeof gameCustomHostnames.$inferSelect;
 type UpsertGameMetadataInput = z.infer<typeof UpsertGameMetadataSchema>;
-/**
- * Response from backend deployment API
- */
-interface BackendDeploymentResponse {
-    /** Unique deployment ID */
-    deploymentId: string;
-    /** Backend API URL */
-    url: string;
-    /** Deployment timestamp */
-    deployedAt: string;
-}
 type Item = typeof items.$inferSelect;
 type InventoryItem = typeof inventoryItems.$inferSelect;
 type ShopListing = typeof shopListings.$inferSelect;
@@ -2837,10 +3011,12 @@ type CharacterComponentWithSpriteUrl = CharacterComponent & {
 type InventoryItemWithItem = Omit<InventoryItem, 'itemId'> & {
     item: Item;
 };
-type HostedGameWithManifest = HostedGame & {
-    manifest: ManifestV1;
+/**
+ * Game with optional manifest metadata from build tools
+ */
+type FetchedGame = (HostedGame | ExternalGame | GameRow) & {
+    manifest?: ManifestV1;
 };
-type FetchedGame = HostedGameWithManifest | GameRow;
 /**
  * Map-related Composite Types
  * Types that combine map, game, and item data for rendering and interaction
@@ -3164,6 +3340,8 @@ interface IntegrationsConfig {
     kv?: boolean;
     /** Bucket storage (optional) */
     bucket?: boolean;
+    /** Authentication (optional) */
+    auth?: boolean;
 }
 /**
  * Unified Playcademy configuration
@@ -3817,6 +3995,14 @@ declare class PlaycademyClient {
         }) => void) | (() => void) | ((isVisible: boolean) => void)) => void;
         removeAllListeners: () => void;
         getListenerCounts: () => Record<string, number>;
+        cdn: {
+            url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
+            fetch: (path: string, options?: RequestInit) => Promise<Response>;
+            json: <T = unknown>(path: string) => Promise<T>;
+            blob: (path: string) => Promise<Blob>;
+            text: (path: string) => Promise<string>;
+            arrayBuffer: (path: string) => Promise<ArrayBuffer>;
+        };
     };
     /** Game management methods (fetch, list, saveState, loadState, sessions) */
     games: {
@@ -3865,15 +4051,17 @@ declare class PlaycademyClient {
             get: () => Promise<DeveloperStatusValue>;
         };
         games: {
-            deploy: {
-                frontend: (slug: string, metadata: UpsertGameMetadataInput, file: File | Blob | null, hooks?: DevUploadHooks) => Promise<Game>;
-                backend: (slug: string, bundle: BackendDeploymentBundle) => Promise<BackendDeploymentResponse>;
-                seed: (slug: string, code: string, environment?: "staging" | "production") => Promise<{
-                    success: boolean;
-                    deploymentId: string;
-                    executedAt: string;
-                }>;
-            };
+            deploy: (slug: string, options: {
+                metadata?: UpsertGameMetadataInput;
+                file?: File | Blob | null;
+                backend?: BackendDeploymentBundle;
+                hooks?: DevUploadHooks;
+            }) => Promise<Game>;
+            seed: (slug: string, code: string, environment?: "staging" | "production") => Promise<{
+                success: boolean;
+                deploymentId: string;
+                executedAt: string;
+            }>;
             upsert: (slug: string, metadata: UpsertGameMetadataInput) => Promise<Game>;
             delete: (gameId: string) => Promise<void>;
             secrets: {
@@ -3899,6 +4087,12 @@ declare class PlaycademyClient {
                 put: (slug: string, key: string, content: Blob | ArrayBuffer | Uint8Array, contentType?: string) => Promise<void>;
                 delete: (slug: string, key: string) => Promise<void>;
             };
+            domains: {
+                add: (slug: string, hostname: string) => Promise<GameCustomHostname>;
+                list: (slug: string) => Promise<GameCustomHostname[]>;
+                status: (slug: string, hostname: string, refresh?: boolean) => Promise<GameCustomHostname>;
+                delete: (slug: string, hostname: string) => Promise<void>;
+            };
         };
         items: {
             create: (gameId: string, slug: string, itemData: Omit<InsertItemInput, "slug" | "gameId">) => Promise<Item>;
@@ -3935,10 +4129,10 @@ declare class PlaycademyClient {
         };
         items: {
             create: (props: InsertItemInput) => Promise<{
-                metadata: unknown;
                 type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
-                slug: string;
                 id: string;
+                metadata: unknown;
+                slug: string;
                 createdAt: Date;
                 gameId: string | null;
                 displayName: string;
@@ -3947,10 +4141,10 @@ declare class PlaycademyClient {
                 imageUrl: string | null;
             }>;
             get: (itemId: string) => Promise<{
-                metadata: unknown;
                 type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
-                slug: string;
                 id: string;
+                metadata: unknown;
+                slug: string;
                 createdAt: Date;
                 gameId: string | null;
                 displayName: string;
@@ -3959,10 +4153,10 @@ declare class PlaycademyClient {
                 imageUrl: string | null;
             }>;
             list: () => Promise<{
-                metadata: unknown;
                 type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
-                slug: string;
                 id: string;
+                metadata: unknown;
+                slug: string;
                 createdAt: Date;
                 gameId: string | null;
                 displayName: string;
@@ -3971,10 +4165,10 @@ declare class PlaycademyClient {
                 imageUrl: string | null;
             }[]>;
             update: (itemId: string, props: UpdateItemInput) => Promise<{
-                metadata: unknown;
                 type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
-                slug: string;
                 id: string;
+                metadata: unknown;
+                slug: string;
                 createdAt: Date;
                 gameId: string | null;
                 displayName: string;
@@ -4228,6 +4422,30 @@ declare class PlaycademyClient {
     };
 }
 
+/**
+ * Base error class for Cademy SDK specific errors.
+ */
+declare class PlaycademyError extends Error {
+    constructor(message: string);
+}
+declare class ApiError extends Error {
+    status: number;
+    details: unknown;
+    constructor(status: number, message: string, details: unknown);
+}
+/**
+ * Extract useful error information from an API error
+ * Useful for displaying errors to users in a friendly way
+ */
+interface ApiErrorInfo {
+    status: number;
+    statusText: string;
+    error?: string;
+    message?: string;
+    details?: unknown;
+}
+declare function extractApiErrorInfo(error: unknown): ApiErrorInfo | null;
+
 /**
  * @fileoverview Playcademy Messaging System
  *
@@ -4772,5 +4990,5 @@ declare class PlaycademyMessaging {
  */
 declare const messaging: PlaycademyMessaging;
 
-export { MessageEvents, PlaycademyClient, messaging };
-export type { DevUploadEvent, DevUploadHooks };
+export { ApiError, MessageEvents, PlaycademyClient, PlaycademyError, extractApiErrorInfo, messaging };
+export type { ApiErrorInfo, DevUploadEvent, DevUploadHooks };