@api-emulator/core 0.5.2

package/README.md

@@ -0,0 +1,51 @@
+# @api-emulator/core
+
+HTTP server, in-memory store, plugin interface, and middleware for emulate service plugins.
+
+Part of [emulate](https://github.com/jsj/api-emulator) — local drop-in replacement services for CI and no-network sandboxes.
+
+## Install
+
+```bash
+npm install @api-emulator/core
+```
+
+## Overview
+
+The core provides the shared infrastructure that every service plugin builds on:
+
+- **Store** — a generic in-memory store with typed `Collection<T>` instances supporting CRUD, indexing, filtering, and pagination
+- **Server** — Hono-based HTTP server with automatic port management
+- **Middleware** — bearer token auth, error handling, CORS
+- **UI** — shared authorization/consent page rendering with bundled fonts
+- **Persistence** — pluggable save/load adapters for state durability
+
+## Persistence
+
+### File persistence
+
+For local development, use the built-in file adapter:
+
+```typescript
+import { filePersistence } from '@api-emulator/core'
+
+persistence: filePersistence('.api-emulator/state.json')
+```
+
+### Custom adapter
+
+Any object with `load` and `save` methods works:
+
+```typescript
+const kvAdapter = {
+  async load() { return await kv.get('api-emulator-state') },
+  async save(data: string) { await kv.set('api-emulator-state', data) },
+}
+```
+
+The persistence adapter is called on cold start (load) and after every mutating request (save). Saves are serialized via an internal queue to prevent race conditions.
+
+## Links
+
+- [Full documentation](https://api-emulator.jsj.sh)
+- [GitHub](https://github.com/jsj/api-emulator)

package/dist/index.d.ts

@@ -0,0 +1,317 @@
+import * as hono_types from 'hono/types';
+import * as hono from 'hono';
+import { Context, Next, Hono, ErrorHandler, MiddlewareHandler } from 'hono';
+
+interface Entity {
+    id: number;
+    created_at: string;
+    updated_at: string;
+}
+type InsertInput<T extends Entity> = Omit<T, "id" | "created_at" | "updated_at"> & {
+    id?: number;
+};
+type FilterFn<T> = (item: T) => boolean;
+type SortFn<T> = (a: T, b: T) => number;
+interface QueryOptions<T> {
+    filter?: FilterFn<T>;
+    sort?: SortFn<T>;
+    page?: number;
+    per_page?: number;
+}
+interface PaginatedResult<T> {
+    items: T[];
+    total_count: number;
+    page: number;
+    per_page: number;
+    has_next: boolean;
+    has_prev: boolean;
+}
+interface CollectionSnapshot<T extends Entity = Entity> {
+    items: T[];
+    autoId: number;
+    indexFields: string[];
+}
+interface StoreSnapshot {
+    collections: Record<string, CollectionSnapshot>;
+    data: Record<string, unknown>;
+}
+declare function serializeValue(value: unknown): unknown;
+declare function deserializeValue(value: unknown): unknown;
+declare class Collection<T extends Entity> {
+    private indexFields;
+    private items;
+    private indexes;
+    private autoId;
+    readonly fieldNames: string[];
+    constructor(indexFields?: (keyof T)[]);
+    private addToIndex;
+    private removeFromIndex;
+    insert(data: InsertInput<T>): T;
+    get(id: number): T | undefined;
+    findBy(field: keyof T, value: T[keyof T] | string | number): T[];
+    findOneBy(field: keyof T, value: T[keyof T] | string | number): T | undefined;
+    update(id: number, data: Partial<T>): T | undefined;
+    delete(id: number): boolean;
+    all(): T[];
+    query(options?: QueryOptions<T>): PaginatedResult<T>;
+    count(filter?: FilterFn<T>): number;
+    clear(): void;
+    snapshot(): CollectionSnapshot<T>;
+    restore(snap: CollectionSnapshot<T>): void;
+}
+declare class Store {
+    private collections;
+    private _data;
+    collection<T extends Entity>(name: string, indexFields?: (keyof T)[]): Collection<T>;
+    getData<V>(key: string): V | undefined;
+    setData<V>(key: string, value: V): void;
+    reset(): void;
+    snapshot(): StoreSnapshot;
+    restore(snap: StoreSnapshot): void;
+}
+
+interface WebhookSubscription {
+    id: number;
+    url: string;
+    events: string[];
+    active: boolean;
+    secret?: string;
+    owner: string;
+    repo?: string;
+}
+interface WebhookDelivery {
+    id: number;
+    hook_id: number;
+    event: string;
+    action?: string;
+    payload: unknown;
+    status_code: number | null;
+    delivered_at: string;
+    duration: number | null;
+    success: boolean;
+}
+declare class WebhookDispatcher {
+    private subscriptions;
+    private deliveries;
+    private subscriptionIdCounter;
+    private deliveryIdCounter;
+    register(sub: Omit<WebhookSubscription, "id"> & {
+        id?: number;
+    }): WebhookSubscription;
+    unregister(id: number): boolean;
+    getSubscription(id: number): WebhookSubscription | undefined;
+    getSubscriptions(owner?: string, repo?: string): WebhookSubscription[];
+    updateSubscription(id: number, data: Partial<Pick<WebhookSubscription, "url" | "events" | "active" | "secret">>): WebhookSubscription | undefined;
+    dispatch(event: string, action: string | undefined, payload: unknown, owner: string, repo?: string): Promise<void>;
+    getDeliveries(hookId?: number): WebhookDelivery[];
+    clear(): void;
+}
+
+interface AuthUser {
+    login: string;
+    id: number;
+    scopes: string[];
+}
+interface AuthApp {
+    appId: number;
+    slug: string;
+    name: string;
+}
+interface AuthInstallation {
+    installationId: number;
+    appId: number;
+    permissions: Record<string, string>;
+    repositoryIds: number[];
+    repositorySelection: "all" | "selected";
+}
+type TokenMap = Map<string, AuthUser>;
+interface TokenEntry {
+    token: string;
+    login: string;
+    id: number;
+    scopes: string[];
+}
+declare function serializeTokenMap(tokenMap: TokenMap): TokenEntry[];
+declare function restoreTokenMap(tokenMap: TokenMap, tokens: TokenEntry[]): void;
+type AppEnv = {
+    Variables: {
+        authUser?: AuthUser;
+        authApp?: AuthApp;
+        authToken?: string;
+        authScopes?: string[];
+        docsUrl?: string;
+    };
+};
+interface AppKeyResolver {
+    (appId: number): {
+        privateKey: string;
+        slug: string;
+        name: string;
+    } | null;
+}
+interface AuthFallback {
+    login: string;
+    id: number;
+    scopes: string[];
+}
+declare function authMiddleware(tokens: TokenMap, appKeyResolver?: AppKeyResolver, fallbackUser?: AuthFallback): (c: Context, next: Next) => Promise<void>;
+declare function requireAuth(): (c: Context, next: Next) => Promise<(Response & hono.TypedResponse<{
+    message: string;
+    documentation_url: string;
+}, 401, "json">) | undefined>;
+declare function requireAppAuth(): (c: Context, next: Next) => Promise<(Response & hono.TypedResponse<{
+    message: string;
+    documentation_url: string;
+}, 401, "json">) | undefined>;
+
+interface RouteContext {
+    app: Hono<AppEnv>;
+    store: Store;
+    webhooks: WebhookDispatcher;
+    baseUrl: string;
+    tokenMap?: TokenMap;
+}
+interface ServicePlugin {
+    name: string;
+    register(app: Hono<AppEnv>, store: Store, webhooks: WebhookDispatcher, baseUrl: string, tokenMap?: TokenMap): void;
+    seed?(store: Store, baseUrl: string): void;
+}
+
+interface ServerOptions {
+    port?: number;
+    baseUrl?: string;
+    docsUrl?: string;
+    tokens?: Record<string, {
+        login: string;
+        id: number;
+        scopes?: string[];
+    }>;
+    appKeyResolver?: AppKeyResolver;
+    fallbackUser?: AuthFallback;
+}
+declare function createServer(plugin: ServicePlugin, options?: ServerOptions): {
+    app: Hono<AppEnv, hono_types.BlankSchema, "/">;
+    store: Store;
+    webhooks: WebhookDispatcher;
+    port: number;
+    baseUrl: string;
+    tokenMap: TokenMap;
+};
+
+interface FixtureInteraction {
+    service: string;
+    method: string;
+    endpoint: string;
+    request: unknown;
+    response: unknown;
+    status?: number;
+    recordedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+interface StoreFixture {
+    version: 1;
+    service: string;
+    capturedAt: string;
+    store: StoreSnapshot;
+    interactions?: FixtureInteraction[];
+    metadata?: Record<string, unknown>;
+}
+interface StoreFixtureOptions {
+    capturedAt?: string;
+    interactions?: FixtureInteraction[];
+    metadata?: Record<string, unknown>;
+}
+type FixtureSource = StoreSnapshot | StoreFixture;
+declare function createStoreFixture(service: string, store: StoreSnapshot, options?: StoreFixtureOptions): StoreFixture;
+declare function isStoreFixture(source: FixtureSource): source is StoreFixture;
+declare function fixtureStoreSnapshot(source: FixtureSource): StoreSnapshot;
+
+/**
+ * Use with `app.onError(...)`. Hono routes handler throws to the app error handler, not to outer middleware try/catch.
+ */
+declare function createApiErrorHandler(documentationUrl?: string): ErrorHandler;
+/** Sets `docsUrl` on the context for successful responses; register `createApiErrorHandler` for thrown `ApiError`s. */
+declare function createErrorHandler(documentationUrl?: string): MiddlewareHandler;
+declare const errorHandler: MiddlewareHandler;
+declare class ApiError extends Error {
+    status: number;
+    errors?: Array<{
+        resource: string;
+        field: string;
+        code: string;
+    }> | undefined;
+    constructor(status: number, message: string, errors?: Array<{
+        resource: string;
+        field: string;
+        code: string;
+    }> | undefined);
+}
+declare function notFound(resource?: string): ApiError;
+declare function validationError(message: string, errors?: ApiError["errors"]): ApiError;
+declare function unauthorized(): ApiError;
+declare function forbidden(): ApiError;
+declare function parseJsonBody(c: Context): Promise<Record<string, unknown>>;
+
+interface PaginationParams {
+    page: number;
+    per_page: number;
+}
+declare function parsePagination(c: Context): PaginationParams;
+declare function setLinkHeader(c: Context, totalCount: number, page: number, perPage: number): void;
+
+declare function escapeHtml(s: string): string;
+declare function escapeAttr(s: string): string;
+declare function renderCardPage(title: string, subtitle: string, body: string, service?: string): string;
+declare function renderErrorPage(title: string, message: string, service?: string): string;
+declare function renderSettingsPage(title: string, sidebarHtml: string, bodyHtml: string, service?: string): string;
+interface InspectorTab {
+    id: string;
+    label: string;
+    href: string;
+}
+declare function renderInspectorPage(title: string, tabs: InspectorTab[], activeTab: string, body: string, service?: string): string;
+declare function renderFormPostPage(action: string, fields: Record<string, string>, service?: string): string;
+interface CheckoutLineItem {
+    name: string;
+    quantity: number;
+    unitPrice: number;
+    totalPrice: number;
+    currency: string;
+}
+interface CheckoutPageOptions {
+    merchantName?: string;
+    lineItems: CheckoutLineItem[];
+    subtotal: number;
+    total: number;
+    currency: string;
+    sessionId: string;
+    cancelUrl?: string | null;
+}
+declare function renderCheckoutPage(opts: CheckoutPageOptions, service?: string): string;
+interface UserButtonOptions {
+    letter: string;
+    login: string;
+    name?: string;
+    email?: string;
+    formAction: string;
+    hiddenFields: Record<string, string>;
+}
+declare function renderUserButton(opts: UserButtonOptions): string;
+
+declare function registerFontRoutes(app: Hono<AppEnv>): void;
+
+declare function normalizeUri(uri: string): string;
+declare function matchesRedirectUri(incoming: string, registered: string[]): boolean;
+declare function constantTimeSecretEqual(a: string, b: string): boolean;
+declare function bodyStr(v: unknown): string;
+declare function parseCookies(header: string): Record<string, string>;
+
+declare function debug(label: string, ...args: unknown[]): void;
+
+interface PersistenceAdapter {
+    load(): Promise<string | null>;
+    save(data: string): Promise<void>;
+}
+declare function filePersistence(path: string): PersistenceAdapter;
+
+export { ApiError, type AppEnv, type AppKeyResolver, type AuthApp, type AuthFallback, type AuthInstallation, type AuthUser, type CheckoutLineItem, type CheckoutPageOptions, Collection, type CollectionSnapshot, type Entity, type FilterFn, type FixtureInteraction, type FixtureSource, type InsertInput, type InspectorTab, type PaginatedResult, type PaginationParams, type PersistenceAdapter, type QueryOptions, type RouteContext, type ServerOptions, type ServicePlugin, type SortFn, Store, type StoreFixture, type StoreFixtureOptions, type StoreSnapshot, type TokenEntry, type TokenMap, type UserButtonOptions, type WebhookDelivery, WebhookDispatcher, type WebhookSubscription, authMiddleware, bodyStr, constantTimeSecretEqual, createApiErrorHandler, createErrorHandler, createServer, createStoreFixture, debug, deserializeValue, errorHandler, escapeAttr, escapeHtml, filePersistence, fixtureStoreSnapshot, forbidden, isStoreFixture, matchesRedirectUri, normalizeUri, notFound, parseCookies, parseJsonBody, parsePagination, registerFontRoutes, renderCardPage, renderCheckoutPage, renderErrorPage, renderFormPostPage, renderInspectorPage, renderSettingsPage, renderUserButton, requireAppAuth, requireAuth, restoreTokenMap, serializeTokenMap, serializeValue, setLinkHeader, unauthorized, validationError };