playcademy 0.1.0

package/dist/templates/backend-config.js.template

@@ -0,0 +1,6 @@
+
+
+    // Custom API routes directory
+    backend: {
+        directory: '{{API_DIRECTORY}}', // defaults to 'api'
+    },

package/dist/templates/integrations-config.js.template

@@ -0,0 +1,7 @@
+
+
+    // External integrations
+    // See https://docs.playcademy.com/integrations for more details
+    integrations: {
+{{INTEGRATIONS_CONTENT}}
+    },

package/dist/templates/playcademy.config.js.template

@@ -0,0 +1,4 @@
+/** @type {import('playcademy/types').PlaycademyConfig} */
+export default {
+    name: '{{GAME_NAME}}',{{GAME_DESCRIPTION}}{{GAME_EMOJI}}{{BACKEND_CONFIG}}{{INTEGRATIONS_CONFIG}}
+}

package/dist/templates/playcademy.config.json.template

@@ -0,0 +1,3 @@
+{
+    "name": "{{GAME_NAME}}"{{GAME_DESCRIPTION}}{{GAME_EMOJI}}{{BACKEND_CONFIG}}{{INTEGRATIONS_CONFIG}}
+}

package/dist/templates/sample-route.ts

@@ -0,0 +1,38 @@
+/**
+ * Sample API route
+ *
+ * This route will be available at: https://<your-game-slug>.playcademy.gg/api/hello
+ */
+import type { Context } from 'hono'
+
+/**
+ * GET /api/hello
+ */
+export async function GET(c: Context): Promise<Response> {
+    return c.json({
+        message: 'Hello from your game backend!',
+        timestamp: new Date().toISOString(),
+    })
+}
+
+/**
+ * POST /api/hello
+ */
+export async function POST(c: Context): Promise<Response> {
+    const body = await c.req.json()
+
+    return c.json({
+        message: 'Received your data!',
+        received: body,
+    })
+}
+
+/**
+ * Environment variables available via c.env:
+ * - c.env.PLAYCADEMY_API_KEY - Game-scoped API key for calling Playcademy APIs
+ * - c.env.GAME_ID - Your game's unique ID
+ * - c.env.PLAYCADEMY_BASE_URL - Playcademy platform URL
+ *
+ * Access the SDK client:
+ * - const sdk = c.get('sdk') - Pre-initialized PlaycademyClient
+ */

package/dist/templates/timeback-config.js.template

@@ -0,0 +1,17 @@
+        // TimeBack integration configuration
+        // See https://docs.playcademy.com/timeback for more details
+        timeback: {
+            // Optional: customize organization
+            // organization: {
+            //     name: 'My School',
+            //     type: 'school',
+            // },
+            course: {
+                subjects: {{SUBJECTS}},
+                grades: {{GRADES}},
+                // Optional: customize course details
+                // title: 'Custom Course Title',
+                // courseCode: 'COURSE-101',
+                // level: 'Elementary',
+            },
+        },

package/dist/types.d.ts

@@ -0,0 +1,628 @@
+import { UserInfo, ApiKey, BackendDeploymentResponse } from '@playcademy/data/types';
+import { OrganizationConfig, CourseConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/timeback/types';
+export { ComponentConfig, ComponentResourceConfig, CourseConfig, DerivedComponentConfig, DerivedComponentResourceConfig, DerivedCourseConfig, DerivedOrganizationConfig, DerivedResourceConfig, DerivedTimebackConfig, OrganizationConfig, ResourceConfig, TimebackGrade, TimebackSourcedIds, TimebackSubject } from '@playcademy/timeback/types';
+import { PlaycademyClient } from '@playcademy/sdk';
+import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
+
+/**
+ * Type of authentication token
+ * Duplicated from SDK to avoid circular dependency
+ */
+type TokenType = 'session' | 'apiKey' | 'gameJwt';
+/**
+ * Authentication profile stored for a user
+ * CLI-specific type for managing stored credentials
+ */
+interface AuthProfile {
+    token: string;
+    /** Type of token to determine how to use it in API calls */
+    tokenType: TokenType;
+    /** User ID associated with the token (may not be present for API keys) */
+    userId?: string;
+    email?: string;
+    /** ISO 8601 date string - when the token expires (if applicable) */
+    expiresAt?: string;
+}
+/**
+ * The complete auth store structure
+ * CLI-specific type for ~/.playcademy/auth.json
+ */
+interface AuthStore {
+    /** Default authentication profile used when no profile is specified */
+    default: AuthProfile | null;
+    /** Named authentication profiles for different environments/contexts */
+    profiles: Record<string, AuthProfile>;
+}
+/**
+ * Login credentials for email/password authentication
+ */
+interface LoginCredentials {
+    email: string;
+    password: string;
+}
+/**
+ * Login response from email/password authentication
+ */
+interface LoginResponse {
+    /** Session token received from login */
+    token: string;
+    /** Always 'session' for email/password login */
+    tokenType: 'session';
+    /** User information associated with the token */
+    user: UserInfo;
+    /** ISO 8601 date string - when the session expires */
+    expiresAt: string;
+}
+/**
+ * API key creation response
+ * Extends ApiKey with the actual key on creation
+ */
+interface ApiKeyWithSecret extends ApiKey {
+    /** The actual API key - only present when creating a new key */
+    apiKey: string;
+}
+
+/**
+ * API configuration derived from environment
+ */
+interface ApiConfig {
+    /** Base URL for API requests (e.g., https://hub.playcademy.com) */
+    baseUrl: string;
+    /** Current environment being targeted */
+    environment: 'staging' | 'production';
+}
+/**
+ * Options for API requests
+ */
+interface ApiRequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** Request body data - will be JSON stringified */
+    body?: unknown;
+    /** Additional headers to include in the request */
+    headers?: Record<string, string>;
+    /** Auth profile to use for this request (defaults to 'default') */
+    profile?: string;
+}
+/**
+ * Standard API error response
+ */
+interface ApiErrorResponse {
+    /** Error code/type for programmatic handling */
+    error: string;
+    /** Human-readable error message */
+    message: string;
+    statusCode: number;
+}
+/**
+ * Better-auth sign-in response
+ */
+interface SignInResponse {
+    /** Session token */
+    token: string;
+    /** User information */
+    user: {
+        id: string;
+        email: string;
+    };
+    /** ISO 8601 date string - when the session expires */
+    expiresAt: string;
+}
+/**
+ * Better-auth API key creation response
+ */
+interface CreateApiKeyResponse {
+    /** The actual API key - only shown once */
+    apiKey: string;
+    /** Key metadata */
+    key: {
+        id: string;
+        name: string | null;
+        expiresAt: string | null;
+        createdAt: string;
+    };
+}
+/**
+ * Better-auth API key list item
+ */
+interface ApiKeyListItem {
+    id: string;
+    name: string | null;
+    start: string;
+    enabled: boolean;
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    lastRequest: string | null;
+    requestCount: number;
+}
+
+/**
+ * @fileoverview Server SDK Type Definitions
+ *
+ * TypeScript type definitions for the server-side Playcademy SDK.
+ * Includes configuration types, client state, and re-exported TimeBack types.
+ */
+
+/**
+ * TimeBack integration configuration for Playcademy config file
+ */
+interface TimebackIntegrationConfig {
+    /** Organization overrides */
+    organization?: Partial<OrganizationConfig>;
+    /** Course configuration (subjects and grades REQUIRED) */
+    course: CourseConfig;
+    /** Component overrides */
+    component?: Partial<ComponentConfig>;
+    /** Resource overrides */
+    resource?: Partial<ResourceConfig>;
+    /** Component-Resource link overrides */
+    componentResource?: Partial<ComponentResourceConfig>;
+}
+/**
+ * Integrations configuration
+ */
+interface IntegrationsConfig {
+    /** TimeBack integration (optional) */
+    timeback?: TimebackIntegrationConfig;
+}
+/**
+ * Unified Playcademy configuration
+ * Used for playcademy.config.{js,json}
+ */
+interface PlaycademyConfig {
+    /** Game name */
+    name: string;
+    /** Game description */
+    description?: string;
+    /** Game emoji icon */
+    emoji?: string;
+    /** Build command to run before deployment */
+    buildCommand?: string[];
+    /** Path to build output */
+    buildPath?: string;
+    /** Game type */
+    gameType?: 'hosted' | 'external';
+    /** External URL (for external games) */
+    externalUrl?: string;
+    /** Game platform */
+    platform?: 'web' | 'unity' | 'godot';
+    /** Backend configuration */
+    backend?: {
+        /** Custom API routes directory (defaults to 'api') */
+        directory?: string;
+    };
+    /** External integrations */
+    integrations?: IntegrationsConfig;
+}
+
+type GameMetadata = {
+    description?: string;
+    emoji?: string;
+    [key: string]: unknown;
+};
+declare const games: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "games";
+    schema: undefined;
+    columns: {
+        id: drizzle_orm_pg_core.PgColumn<{
+            name: "id";
+            tableName: "games";
+            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;
+        }, {}, {}>;
+        developerId: drizzle_orm_pg_core.PgColumn<{
+            name: "developer_id";
+            tableName: "games";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        slug: drizzle_orm_pg_core.PgColumn<{
+            name: "slug";
+            tableName: "games";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 255;
+        }>;
+        displayName: drizzle_orm_pg_core.PgColumn<{
+            name: "display_name";
+            tableName: "games";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 255;
+        }>;
+        version: drizzle_orm_pg_core.PgColumn<{
+            name: "version";
+            tableName: "games";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 50;
+        }>;
+        gameType: drizzle_orm_pg_core.PgColumn<{
+            name: "game_type";
+            tableName: "games";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "hosted" | "external";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["hosted", "external"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        assetBundleBase: drizzle_orm_pg_core.PgColumn<{
+            name: "asset_bundle_base";
+            tableName: "games";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        externalUrl: drizzle_orm_pg_core.PgColumn<{
+            name: "external_url";
+            tableName: "games";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        platform: drizzle_orm_pg_core.PgColumn<{
+            name: "platform";
+            tableName: "games";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "web" | "godot" | "unity";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["web", "godot", "unity"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        mapElementId: drizzle_orm_pg_core.PgColumn<{
+            name: "map_element_id";
+            tableName: "games";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        metadata: drizzle_orm_pg_core.PgColumn<{
+            name: "metadata";
+            tableName: "games";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: GameMetadata;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: GameMetadata;
+        }>;
+        createdAt: drizzle_orm_pg_core.PgColumn<{
+            name: "created_at";
+            tableName: "games";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            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: "games";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+type GameRow = typeof games.$inferSelect;
+type BaseGame = Omit<GameRow, 'gameType' | 'assetBundleBase' | 'externalUrl'>;
+type HostedGame = BaseGame & {
+    gameType: 'hosted';
+    assetBundleBase: string;
+    externalUrl: null;
+};
+type ExternalGame = BaseGame & {
+    gameType: 'external';
+    assetBundleBase: null;
+    externalUrl: string;
+};
+type Game = HostedGame | ExternalGame;
+
+/**
+ * Deployed game tracking - maps project directories to game IDs
+ */
+interface DeployedGameInfo {
+    gameId: string;
+    lastDeployedAt: string;
+    buildPath?: string;
+    buildHash?: string;
+    buildSize?: number;
+    backendHash?: string;
+    backendSize?: number;
+    backendDeployedAt?: string;
+}
+interface GameStore {
+    [projectPath: string]: DeployedGameInfo;
+}
+/**
+ * Backend deployment response with code hash for change detection
+ */
+interface BackendDeploymentWithHash extends BackendDeploymentResponse {
+    /** SHA-256 hash of the deployed backend code */
+    backendHash: string;
+    /** Size of the deployed backend code in bytes */
+    backendSize: number;
+}
+/**
+ * Deployment context containing all information needed for deployment
+ */
+interface DeploymentContext {
+    config: DeployConfig;
+    fullConfig: PlaycademyConfig | null;
+    configFileName: string | null;
+    client: PlaycademyClient;
+    projectPath: string;
+    existingGame?: Game;
+    deployedGameInfo?: DeployedGameInfo;
+    isNewDeployment: boolean;
+    buildHash?: string;
+    buildSize?: number;
+    previousBuildHash?: string;
+    previousBuildSize?: number;
+    previousBackendHash?: string;
+    previousBackendSize?: number;
+    isDryRun: boolean;
+    deployBackend: boolean;
+    verbose: boolean;
+}
+/**
+ * Analysis of what changed in an update
+ */
+interface DeploymentChanges {
+    config: boolean;
+    build: boolean | undefined;
+    backend: boolean | undefined;
+}
+/**
+ * Plan for what needs to be deployed
+ */
+interface DeploymentPlan {
+    action: 'deploy-new' | 'update-existing' | 'no-changes';
+    gameType: 'hosted' | 'external';
+    shouldDeployFrontend: boolean;
+    shouldDeployBackend: boolean;
+    changes?: DeploymentChanges;
+    currentBackendSize?: number;
+}
+/**
+ * Result of a deployment
+ */
+interface DeploymentResult {
+    game: Game;
+    backendDeployment?: BackendDeploymentWithHash | null;
+}
+/**
+ * Deployment configuration
+ *
+ * Configuration for deploying a game to Playcademy.
+ * Can be provided via CLI options, playcademy.json file, or package.json.
+ */
+interface DeployConfig {
+    /** Game slug (URL-friendly identifier) */
+    slug?: string;
+    /** Display name for the game */
+    displayName?: string;
+    /** Game description */
+    description?: string;
+    /** Emoji icon for the game */
+    emoji?: string;
+    /** Path to the build directory or zip file */
+    buildPath?: string;
+    /** Game platform (defaults to 'web') */
+    platform?: 'web' | 'unity' | 'godot';
+    /** Game type */
+    gameType?: 'hosted' | 'external';
+    /** External URL for external games */
+    externalUrl?: string;
+}
+interface DeployNewGameOptions {
+    client: PlaycademyClient;
+    config: DeployConfig;
+    isDryRun: boolean;
+    projectPath: string;
+    buildHash?: string;
+    backend?: boolean;
+}
+interface UpdateExistingGameOptions {
+    configFileName?: string | null;
+    client: PlaycademyClient;
+    config: DeployConfig;
+    backend?: boolean;
+    existingGame: Game;
+    isDryRun: boolean;
+    projectPath: string;
+    previousBuildHash?: string;
+    currentBuildHash?: string;
+    previousBuildSize?: number;
+    currentBuildSize?: number;
+    previousBackendHash?: string;
+    previousBackendSize?: number;
+    verbose?: boolean;
+}
+
+/**
+ * Types for the CLI local HTTP server that handles OAuth callbacks
+ */
+/**
+ * Callback data received from the Playcademy server after SSO authentication
+ */
+interface SsoCallbackData {
+    /** The session token from SSO authentication */
+    sessionToken: string;
+    /** User's email address */
+    email: string;
+    /** User's ID */
+    userId: string;
+}
+/**
+ * Result from starting and running the callback server
+ */
+interface CallbackServerResult {
+    /** Whether the callback was successful */
+    success: boolean;
+    /** The callback data if successful */
+    data?: SsoCallbackData;
+    /** Error message if unsuccessful */
+    error?: string;
+}
+
+/**
+ * Preview options
+ */
+interface PreviewOptions {
+    /** Path to project directory (defaults to current directory) */
+    project?: string;
+    /** Preview duration in hours (defaults to 24, max 168) */
+    duration?: number;
+    /** Optional password protection for the preview */
+    password?: string;
+    /** Description or message for the preview */
+    message?: string;
+}
+/**
+ * Preview response
+ */
+interface PreviewResponse {
+    /** Unique preview identifier */
+    id: string;
+    /** URL where the preview is accessible */
+    url: string;
+    /** ISO 8601 date string - when the preview expires */
+    expiresAt: string;
+    /** Base64 encoded QR code image for easy mobile access */
+    qrCode?: string;
+}
+
+export type { ApiConfig, ApiErrorResponse, ApiKeyListItem, ApiKeyWithSecret, ApiRequestOptions, AuthProfile, AuthStore, BackendDeploymentWithHash, CallbackServerResult, CreateApiKeyResponse, DeployConfig, DeployNewGameOptions, DeployedGameInfo, DeploymentChanges, DeploymentContext, DeploymentPlan, DeploymentResult, GameStore, IntegrationsConfig, LoginCredentials, LoginResponse, PlaycademyConfig, PreviewOptions, PreviewResponse, SignInResponse, SsoCallbackData, TimebackIntegrationConfig, TokenType, UpdateExistingGameOptions };