puter/extensions/api.d.ts

import type APIError from '@heyputer/backend/src/api/APIError.js';
import type query from '@heyputer/backend/src/om/query/query';
import type { Actor } from '@heyputer/backend/src/services/auth/Actor.js';
import type { ServicesMap } from '@heyputer/backend/src/services/BaseService.d.ts';
import type { BaseDatabaseAccessService } from '@heyputer/backend/src/services/database/BaseDatabaseAccessService.d.ts';
import type { DynamoKVStore } from '@heyputer/backend/src/services/repositories/DynamoKVStore/DynamoKVStore.ts';
import type { IUser } from '@heyputer/backend/src/services/User.js';
import type { Context } from '@heyputer/backend/src/util/context.js';
import type kvjs from '@heyputer/kv.js';
import type { RequestHandler } from 'express';
import type { Cluster } from 'ioredis';
import type FSNodeContext from '../src/backend/src/filesystem/FSNodeContext.js';
import type helpers from '../src/backend/src/helpers.js';
import type { ICompleteArguments } from '../src/backend/src/services/ai/chat/providers/types.ts';
import type * as ExtensionControllerExports from './ExtensionController/src/ExtensionController.ts';
import type { s3ClientProvider } from '../src/backend/src/clients/s3/s3ClientProvider.js';

declare global {
    namespace Express {
        interface Request {
            services: {
                get: <T extends keyof ServicesMap | (string & {})>(
                    string: T,
                ) => T extends keyof ServicesMap ? ServicesMap[T] : unknown;
            };
            actor?: Actor;
            rawBody: Buffer;
            /** @deprecated use actor instead */
            user: IUser;
        }
    }
}

export type { Cluster } from 'ioredis';

export interface EndpointOptions {
    allowedMethods?: string[];
    subdomain?: string;
    noauth?: boolean;
    mw?: RequestHandler[];
    otherOpts?: Record<string, unknown> & {
        json?: boolean;
        noReallyItsJson?: boolean;
    };
}

// Driver interface types
interface ParameterDefinition {
    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
    optional: boolean;
}
interface MethodDefinition {
    description: string;
    parameters: Record<string, ParameterDefinition>;
}
interface DriverInterface {
    description: string;
    methods: Record<string, MethodDefinition>;
}

export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch';

export type AddRouteFunction = (
    path: string,
    options: EndpointOptions,
    handler: RequestHandler,
) => void;

export type RouterMethods = {
    [K in HttpMethod]: {
        (path: string, options: EndpointOptions, handler: RequestHandler): void;
        (path: string, handler: RequestHandler, options?: EndpointOptions): void;
    };
};

interface CoreRuntimeModule {
    util: {
        helpers: typeof helpers;
    };
    redisClient: Cluster;
    kvjs: kvjs
    s3ClientProvider: typeof s3ClientProvider;
    Context: typeof Context;
    APIError: typeof APIError;
}

interface FilesystemModule {
    FSNodeContext: FSNodeContext;
    selectors: unknown;
}

export interface ExtensionEventTypeMap {
    'metering:registerAvailablePolicies': {
        availablePolicies: unknown[]
    },
    'create.drivers': {
        createDriver: (interface: string, service: string, executors: any) => any;
    };
    'create.permissions': {
        grant_to_everyone: (permission: string) => void;
        grant_to_users: (permission: string) => void;
    };
    'create.interfaces': {
        createInterface: (interface: string, interfaces: DriverInterface) => void;
    };
    'puter.gui.addons': {
        bodyContent: string;
        headContent: string;
        guiParams: {
            env: string;
            app_origin: string;
            api_origin: string;
            gui_origin: string;
            asset_dir: string;
            launch_options: unknown;
            app_name_regex: RegExp;
            app_name_max_length: number;
            app_title_max_length: number;
            hosting_domain: string;
            subdomain_regex: RegExp;
            subdomain_max_length: number;
            domain: string;
            protocol: string;
            api_base_url: string;
            app?: { name: string, uid: string } & Record<string, unknown>;
            [key: string]: unknown;
        };
    };
    'app.changed': {
        app_uid: string;
        action: 'updated' | 'deleted';
    };
    'app.privateAccess.check': {
        appUid: string;
        userUid?: string | null;
        requestHost?: string;
        requestPath?: string;
        result: {
            allowed: boolean;
            redirectUrl?: string;
            reason?: string;
            checkedBy?: string;
        };
    };
    'app.privateAccess.resolveLaunch': {
        appUid: string;
        appName?: string;
        userUid?: string | null;
        source?: string;
        args?: Record<string, unknown>;
        result: {
            hasAccess: boolean;
            fallbackAppName?: string;
            fallbackArgs?: Record<string, unknown>;
            reason?: string;
            checkedBy?: string;
        };
    };
    'ai.prompt.validate': {
        actor: Actor;
        actor,
        completionId: string,
        allow: boolean,
        intended_service: string,
        parameters: ICompleteArguments
    }
    'outer.cacheUpdate': { cacheKey: string | string[], ttlSeconds?: number, data?: unknown }
}

interface Extension extends RouterMethods {
    exports: Record<string, unknown>;
    span: (<T>(label: string, fn: () => T) => () => T) & {
        run<T>(label: string, fn: () => T): T;
        run<T>(fn: () => T): T;
    };
    config: Record<string | number | symbol, any>;

    on<E extends keyof ExtensionEventTypeMap>(
        name: E,
        listener: (event: ExtensionEventTypeMap[E], metadata?: { from_outside?: boolean }) => void | Promise<void>
    ): void;
    on<T>(name: string, listener: (event: T, metadata?: { from_outside?: boolean }) => void | Promise<void>): void

    import(module: 'data'): {
        db: BaseDatabaseAccessService;
        kv: DynamoKVStore;
        cache: Cluster;
        s3ClientProvider: typeof s3ClientProvider;
    };
    import(module: 'core'): CoreRuntimeModule;
    import(module: 'fs'): FilesystemModule;
    import(module: 'query'): typeof query;
    import(module: 'extensionController'): typeof ExtensionControllerExports;
    import<T extends `service:${keyof ServicesMap}` | (string & {})>(
        module: T
    ): T extends `service:${infer R extends keyof ServicesMap}`
        ? ServicesMap[R]
        : unknown;
}

declare global {
    // Declare the extension variable
    const extension: Extension;
    const config: Record<string | number | symbol, any>;
    const global_config: Record<string | number | symbol, unknown>;
}