@ebay-dt/bonfire-core

Framework-neutral Bonfire contracts. It provides validated, frozen instance configuration, app-specific session cookie names, runtime identity parsing, and the serializable GitHub CLI login-page model.

Configuration

import { defineConfig } from "@ebay-dt/bonfire-core";

const config = defineConfig({
  appId: "my-app",
  name: "My App",
  auth: {
    github: {
      hostname: "github.com",
    },
  },
});

appId is used to derive an isolated session-cookie name. Hostnames are normalized and validated as plain hostnames without protocols, ports, or paths. Identity values and configuration are validated at runtime, and normalized configuration is deeply frozen.

The package also exports the BonfireIdentity and GitHubCliLoginPageModel types used by the Node, Next.js, and React packages.

Generic theme contracts

Themes are optional instance configuration. A registry declares the themes an application can render and the color schemes each theme supports:

import type { BonfireConfigInput } from "@ebay-dt/bonfire-core";

const config = {
  appId: "my-app",
  name: "My App",
  themes: {
    definitions: [
      {
        id: "alpha",
        label: "Alpha",
        allowedColorSchemes: ["system", "light", "dark"],
      },
      { id: "beta", label: "Beta", allowedColorSchemes: ["dark"] },
    ],
    defaultTheme: "alpha",
    defaultColorScheme: "system",
  },
} satisfies BonfireConfigInput;

ThemeDefinition, ThemeRegistry, and PrototypeTheme are generic contracts; Bonfire does not assign meaning to theme IDs or own their CSS. Prototype metadata may narrow the registry to a default theme, allowed themes, a default scheme, and allowed schemes. All registry and metadata values are normalized, validated, and deeply frozen. parsePrototypeThemeSelection expands the create/edit dialog's switching permissions into a validated PrototypeTheme.

Prototype catalog contracts

Prototype references use a validated login and lowercase kebab-case slug:

import {
  definePrototypeRef,
  getPrototypeUrl,
  parsePrototypePath,
  slugifyPrototypeTitle,
} from "@ebay-dt/bonfire-core";

const ref = definePrototypeRef({
  login: "octocat",
  slug: slugifyPrototypeTitle("Checkout Redesign")!,
});

getPrototypeUrl(ref); // "/octocat/checkout-redesign"
parsePrototypePath("/octocat/checkout-redesign/details"); // ref

Metadata uses authorLogin for the login corresponding to BonfireIdentity.login; authorName corresponds to its nullable name. Metadata is normalized, validated, and deeply frozen by parsePrototypeMetadata. Unknown fields are discarded.

Catalog queries support all, mine, or a validated author login, with recent, alphabetical, and deployed sorting:

import {
  filterPrototypes,
  sortPrototypes,
  type PrototypeCatalogQuery,
} from "@ebay-dt/bonfire-core";

const query: PrototypeCatalogQuery = {
  author: "all",
  sort: "recent",
};
const visible = sortPrototypes(
  filterPrototypes(summaries, query.author, currentLogin),
  query.sort,
);

Prototype lifecycle contracts

Lifecycle commands return stable, framework-neutral results. Failures contain only a machine-readable code; adapters own user-facing messages:

import {
  parseCreatePrototypeInput,
  type LifecycleResult,
} from "@ebay-dt/bonfire-core";

const input = parseCreatePrototypeInput(formValue);
const result: LifecycleResult<unknown> = await create(input);
if (!result.ok) {
  result.error.code; // "invalid-input", "git-failure", etc.
}

Create and duplicate inputs normalize title/description and validate all prototype references. Edit normalizes the title/description together with the owned prototype ref; delete uses the same normalized PrototypeRef command input. Destination identity and slug are intentionally absent from browser input; trusted services derive them from the authenticated identity and normalized title. Create, duplicate, edit, and delete are development-only mutation contracts; production adapters remain public and read-only.

Dirty observation is represented by the finite clean and dirty statuses. It is an observation of the repository, not durable client state. Edit and delete return explicit success values and never expose filesystem paths, Git output, or framework values. Edit preserves the existing ref and URL; delete represents removal of the complete owned prototype directory, including uncommitted files.

Lifecycle errors contain only stable codes, never filesystem paths, Git output, GitHub CLI output, or secrets. Hosts own user-facing copy for codes such as invalid-input, already-exists, repository-busy, working-tree-conflict, git-failure, and filesystem-failure.

Deployment uses the same validated PrototypeCommandInput as other reference-only lifecycle commands. A successful DeploymentValue contains the owned prototype ref, canonical previewUrl, deploymentId, readyState, and an optional warning. Ready states are finite: BLOCKED, BUILDING, CANCELED, ERROR, INITIALIZING, QUEUED, and READY. A ready state is the provider's reported state; Bonfire does not poll the deployment ID.

Deployment is optional and development-only. Core does not define a service endpoint, credentials, deployment target, or { owner, branch } input; trusted Node/Next adapters derive the application ID and login from server configuration and authenticated identity.