@stripe/extensibility-custom-objects-tools 0.40.0

package/dist/extensibility-custom-objects-tools-internal-internal.d.ts

@@ -0,0 +1,475 @@
+import { JsonSchema2020 } from '@formspec/build';
+import * as ts from 'typescript';
+import { UISchema } from '@formspec/build';
+
+/**
+ * Schema artifacts extracted for one action method.
+ *
+ * @internal
+ */
+export declare interface ActionSchemaResult {
+    name: string;
+    methodName: string;
+    apiName: string;
+    input: CustomObjectSchemaArtifacts | null;
+    output: {
+        jsonSchema: JsonSchema2020;
+    };
+    paramsSchema: JsonSchema2020 | Record<string, never>;
+    returnSchema: JsonSchema2020;
+}
+
+/**
+ * Structured result returned by an `afterExecute` hook.
+ * @internal
+ */
+declare interface _AfterExecuteResult {
+    /** Descriptions of side effects that were performed. */
+    readonly sideEffects?: readonly string[];
+}
+
+/**
+ * Structured result returned by a `beforeExecute` hook.
+ *
+ * Returning `{ proceed: false, reason: '...', remediation: '...' }` is a
+ * normal rejection — the user should fix their input. Throwing indicates a
+ * generator defect and should be filed as a bug.
+ *
+ * The discriminated union enforces that `reason` is always present when
+ * `proceed` is `false` — `{ proceed: false }` without a reason is a type error.
+ * @internal
+ */
+declare type _BeforeExecuteResult = {
+    readonly proceed: false;
+    readonly reason: string;
+    readonly remediation?: string;
+} | { readonly proceed: true };
+
+/**
+ * Build schemas, UI specs, platform metadata, and transformed modules for a set of
+ * custom object exports using one shared TypeScript program.
+ *
+ * @internal
+ */
+export declare function buildCustomObjectPackage(options: BuildCustomObjectPackageOptions, dependencies?: {
+    createProgram?: (rootNames: readonly string[], options: ts.CompilerOptions) => ts.Program;
+}): CustomObjectPackageBuildResult;
+
+/**
+ * Options for building a package-scoped custom object artifact set.
+ *
+ * @internal
+ */
+export declare interface BuildCustomObjectPackageOptions {
+    targets: BuildCustomObjectTarget[];
+}
+
+/**
+ * One custom object export to include in a package-scoped build.
+ *
+ * @internal
+ */
+export declare interface BuildCustomObjectTarget {
+    modulePath: string;
+    exportName: string;
+}
+
+/**
+ * Diagnostic emitted while building custom object package artifacts.
+ *
+ * @internal
+ */
+export declare interface BuildDiagnostic {
+    severity: 'error' | 'warning';
+    code: string;
+    message: string;
+    modulePath?: string;
+    exportName?: string;
+}
+
+/**
+ * Backwards-compatible alias for the combined build artifact.
+ *
+ * @internal
+ */
+export declare type CustomObjectBuildArtifact = CustomObjectBuildResult;
+
+/**
+ * Combined schema and metadata artifacts for one custom object export.
+ *
+ * @internal
+ */
+export declare interface CustomObjectBuildResult {
+    platformMetadata: CustomObjectPlatformMetadata;
+    fields: CustomObjectSchemaArtifacts;
+    fieldsSchema: JsonSchema2020;
+    fieldsUiSchema: UISchema | null;
+    actions: Record<string, ActionSchemaResult>;
+    primaryDisplayProperty?: string;
+    secondaryDisplayProperty?: string;
+}
+
+/**
+ * Generator that produces a `.object.ts` custom object definition file.
+ * @internal
+ */
+export declare const _customObjectGenerator: _Generator<_CustomObjectParams>;
+
+/**
+ * Composite generator that produces both the object definition and its test file.
+ * @internal
+ */
+export declare const _customObjectGenerators: _GeneratorRunner<_CustomObjectParams>;
+
+/**
+ * Package-scoped custom object build output.
+ *
+ * @internal
+ */
+export declare interface CustomObjectPackageBuildResult {
+    objects: Record<string, CustomObjectBuildResult>;
+    transformedModules: Record<string, string>;
+    diagnostics: BuildDiagnostic[];
+}
+
+/**
+ * User-provided parameters for the custom object generators.
+ * @internal
+ */
+export declare interface _CustomObjectParams {
+    /** User-provided object name (e.g., "Device", "VehicleRental") */
+    name: string;
+    /** Subfolder containing custom object packages (default: 'custom-objects') */
+    packagesSubfolder?: string;
+}
+
+/**
+ * Platform naming metadata for one built custom object.
+ *
+ * @internal
+ */
+export declare interface CustomObjectPlatformMetadata {
+    modulePath: string;
+    className: string;
+    apiName: string;
+    displayName: string;
+    displayNamePlural: string;
+    apiNamePlural: string;
+}
+
+/**
+ * The JSON Schema and JSON Forms artifacts for one extracted surface.
+ *
+ * @internal
+ */
+export declare interface CustomObjectSchemaArtifacts {
+    jsonSchema: JsonSchema2020;
+    uiSchema: UISchema | null;
+}
+
+/**
+ * Generator that produces the custom-objects workspace scaffolding
+ * (package.json, tsconfig.json). Run before any individual custom object
+ * generators when the workspace doesn't exist yet.
+ * @internal
+ */
+export declare const _customObjectsWorkspaceGenerator: _Generator<_CustomObjectsWorkspaceParams>;
+
+/**
+ * User-provided parameters for the custom-objects workspace scaffolding generator.
+ * Does not require a specific object name — only the subfolder placement matters.
+ * @internal
+ */
+export declare interface _CustomObjectsWorkspaceParams {
+    /** Subfolder containing custom object packages (default: 'custom-objects') */
+    packagesSubfolder?: string;
+}
+
+/**
+ * Generator that produces a `.object.test.ts` test file for a custom object.
+ * @internal
+ */
+export declare const _customObjectTestGenerator: _Generator<_CustomObjectParams>;
+
+/**
+ * Extracts schemas from one custom object export.
+ *
+ * This is a convenience wrapper over the package-scoped builder.
+ *
+ * @internal
+ */
+export declare function extractCustomObjectSchemas(options: ExtractSchemasOptions): CustomObjectBuildResult;
+
+/**
+ * Options for extracting schemas from a custom object class export.
+ *
+ * @internal
+ */
+export declare type ExtractSchemasOptions = BuildCustomObjectTarget;
+
+/**
+ * Outcome of writing a single planned file to disk.
+ * @internal
+ */
+declare interface _FileWriteOutcome {
+    readonly path: string;
+    readonly decision: 'created' | 'identical' | 'overwritten' | 'skipped';
+    readonly proposedContent: string;
+    readonly previousContent?: string;
+    /**
+     * Present only when `decision` is `'skipped'` due to an error (not user choice).
+     * For permission errors, disk errors, etc. Not present on 'created', 'overwritten', or 'identical'.
+     */
+    readonly error?: _WriteError;
+}
+
+/**
+ * A composable unit of code generation.
+ *
+ * A generator combines:
+ * - A `files/` directory tree of Mustache templates that mirrors the output structure
+ * - A `locals()` function that computes template variables from user params
+ * - Optional lifecycle hooks for side effects (manifest updates, config changes)
+ *
+ * @typeParam TParams - User-provided parameters for this generator
+ * @internal
+ */
+declare interface _Generator<TParams extends object> {
+    /**
+     * Compute template variables from user-provided params.
+     *
+     * The returned record serves as the variable scope for both:
+     * - `___token___` resolution in file/directory names (structural placement)
+     * - `{{token}}` Mustache rendering in .mustache file content
+     *
+     * Params are the raw user inputs. Locals are the transformed, computed
+     * fields derived from params (e.g., PascalCase, snake_case, pluralized
+     * forms, default values). All template surfaces consume from locals.
+     *
+     * Path tokens (`___token___`) must resolve to strings.
+     * Content tokens (`{{token}}`) may be any Mustache-compatible value.
+     */
+    locals(params: TParams): Record<string, unknown>;
+    /**
+     * Root directory of this generator (parent of the `files/` subdirectory).
+     * The runner will look for templates under `<filesDir>/files/`.
+     */
+    readonly filesDir: string;
+    /**
+     * Map of template-relative file paths to human-readable descriptions.
+     *
+     * Keys are the literal filename in the `files/` tree (with `___token___`
+     * intact, e.g., `'___objectName___.object.ts.mustache'`). Values may use
+     * Mustache `{{token}}` syntax and are rendered with the generator's locals.
+     *
+     * Example:
+     * ```typescript
+     * descriptions: {
+     *   '___objectName___.object.ts.mustache': 'Defines the {{className}} custom object',
+     * }
+     * ```
+     */
+    readonly descriptions?: Readonly<Record<string, string>>;
+    /**
+     * Run before files are generated (e.g., validate preconditions).
+     *
+     * Return `{ proceed: false, reason: '...', remediation: '...' }` to reject
+     * execution with user-actionable guidance.
+     *
+     * **Throwing** indicates a generator defect, not a user input problem.
+     */
+    beforeExecute?(params: TParams, context: _GeneratorContext): Promise<_BeforeExecuteResult>;
+    /**
+     * Run after files are written (e.g., update manifest, install deps).
+     *
+     * Returns a structured description of side effects performed.
+     *
+     * Note: if `afterExecute` throws, files have already been written to disk.
+     * The error propagates to the caller. Callers should handle this as a
+     * partial-completion scenario.
+     */
+    afterExecute?(params: TParams, context: _GeneratorContext, writeResult: _GeneratorWriteResult): Promise<_AfterExecuteResult>;
+    /**
+     * Return descriptions of side effects that `afterExecute` would perform,
+     * parameterized by the current params. Used for dry-run output.
+     *
+     * Returns a promise so future generators can inspect the filesystem to
+     * produce accurate descriptions.
+     */
+    describeSideEffects?(params: TParams): Promise<readonly string[]>;
+}
+
+/**
+ * Discriminated union of the two generator context shapes.
+ * @internal
+ */
+declare type _GeneratorContext = _ProjectGeneratorContext | _StandaloneGeneratorContext;
+
+/**
+ * Discriminated union of the two execute context shapes.
+ * @internal
+ */
+declare type _GeneratorExecuteContext = _ProjectExecuteContext | _StandaloneExecuteContext;
+
+/**
+ * Result returned by `_GeneratorRunner.execute()`.
+ * @internal
+ */
+declare interface _GeneratorExecuteResult {
+    /** Files that were planned (same as plan().files). */
+    readonly files: readonly _PlannedFile[];
+    /** Preflight results from all `beforeExecute` hooks. */
+    readonly preflightResults: readonly _BeforeExecuteResult[];
+    /** Descriptions of side effects declared by generators. */
+    readonly plannedSideEffects: readonly string[];
+    /** The write result from the caller's `writeFiles` callback. Absent (undefined)
+     * if a preflight check rejected execution. */
+    readonly writeResult: _GeneratorWriteResult | undefined;
+    /** Results from all `afterExecute` hooks. */
+    readonly afterExecuteResults: readonly _AfterExecuteResult[];
+}
+
+/**
+ * Result of `_GeneratorRunner.plan()`.
+ * @internal
+ */
+declare interface _GeneratorPlanResult {
+    /** Files that would be generated. */
+    readonly files: readonly _PlannedFile[];
+    /** Preflight results from all `beforeExecute` hooks. */
+    readonly preflightResults: readonly _BeforeExecuteResult[];
+    /** Descriptions of side effects that `afterExecute` hooks would perform. */
+    readonly plannedSideEffects: readonly string[];
+}
+
+/**
+ * Executes a single `_Generator` (or composite of generators), producing file
+ * outputs and running lifecycle hooks.
+ *
+ * Does NOT write files to disk — that responsibility belongs to the caller.
+ *
+ * @typeParam TParams - User-provided parameters type
+ * @internal
+ */
+declare class _GeneratorRunner<TParams extends object> {
+    #private;
+    constructor(generator: _Generator<TParams> | ReadonlyArray<_Generator<TParams>>);
+    /**
+     * Plan phase — compute all files that would be generated, without writing
+     * anything to disk.
+     *
+     * Also runs `beforeExecute` hooks to collect preflight results, and
+     * `describeSideEffects` to surface planned side effects. Neither of these
+     * write anything or produce observable external effects during plan.
+     *
+     * Use this for dry runs, previews, and testing.
+     *
+     * Validates that all output paths are safe (no `..`, no leading `/`) and
+     * that no two generators produce the same output path.
+     *
+     * @param params - User-provided parameters for the generator
+     * @param context - Generator context (standalone or project). Passed to
+     *   `beforeExecute` hooks. Callers must supply a real context — there is no
+     *   synthetic plan-time sentinel. For dry-run calls outside of a project,
+     *   use a standalone context with an appropriate `targetDir`.
+     */
+    plan(params: TParams, context: _GeneratorContext): Promise<_GeneratorPlanResult>;
+    /**
+     * Execute phase — runs the full lifecycle:
+     * 1. `plan()` to collect preflight results and planned files
+     * 2. If any preflight returned `proceed: false`, return early without writing
+     * 3. `context.writeFiles()` to write files to disk (delegated to caller)
+     * 4. If the write was aborted, return early without calling `afterExecute`
+     * 5. `afterExecute` hooks for all generators with the write result
+     */
+    execute(params: TParams, context: _GeneratorExecuteContext): Promise<_GeneratorExecuteResult>;
+}
+
+/**
+ * Result of writing all planned files to disk.
+ * @internal
+ */
+declare interface _GeneratorWriteResult {
+    readonly fileOutcomes: readonly _FileWriteOutcome[];
+    readonly aborted: boolean;
+}
+
+/**
+ * A single file that a generator intends to create.
+ * @internal
+ */
+declare interface _PlannedFile {
+    readonly path: string;
+    readonly content: string;
+    /**
+     * Human-readable explanation of what this file is and why it is being
+     * created. Rendered from the generator's `descriptions` map using Mustache.
+     */
+    readonly description?: string;
+}
+
+/**
+ * Execute context for project-scoped generators.
+ * @internal
+ */
+declare type _ProjectExecuteContext = _ProjectGeneratorContext & _WriteCapability;
+
+/**
+ * Generator context for a project-scoped invocation.
+ * The generator places files relative to `projectRoot`.
+ * @internal
+ */
+declare interface _ProjectGeneratorContext {
+    readonly scope: 'project';
+    readonly projectRoot: string;
+}
+
+/**
+ * Execute context for standalone generators.
+ * @internal
+ */
+declare type _StandaloneExecuteContext = _StandaloneGeneratorContext & _WriteCapability;
+
+/**
+ * Generator abstraction for composable code generation
+ *
+ * A generator combines a `files/` directory tree of Mustache templates,
+ * a `locals()` function that computes template variables, and optional
+ * lifecycle hooks for side effects (manifest updates, config changes).
+ */
+/**
+ * Generator context for a standalone (non-project) invocation.
+ * The generator places files relative to `targetDir`.
+ * @internal
+ */
+declare interface _StandaloneGeneratorContext {
+    readonly scope: 'standalone';
+    readonly targetDir: string;
+}
+
+/**
+ * Build the canonical lookup key for one package-build target.
+ *
+ * @internal
+ */
+export declare function toObjectKey(target: BuildCustomObjectTarget): string;
+
+/**
+ * Capability mixin that adds `writeFiles` to an execute context.
+ * @internal
+ */
+declare interface _WriteCapability {
+    /** Write generated files to disk. Provided by the caller. */
+    writeFiles(files: readonly _PlannedFile[]): Promise<_GeneratorWriteResult>;
+}
+
+/**
+ * Error detail attached to a file write outcome.
+ * @internal
+ */
+declare interface _WriteError {
+    readonly kind: 'conflict' | 'disk' | 'permission' | 'unknown';
+    readonly message: string;
+}
+
+export { }

package/dist/extensibility-custom-objects-tools-internal-public.d.ts

@@ -0,0 +1,77 @@
+import { JsonSchema2020 } from '@formspec/build';
+import * as ts from 'typescript';
+import { UISchema } from '@formspec/build';
+
+/* Excluded from this release type: ActionSchemaResult */
+
+/* Excluded from this release type: _AfterExecuteResult */
+
+/* Excluded from this release type: _BeforeExecuteResult */
+
+/* Excluded from this release type: buildCustomObjectPackage */
+
+/* Excluded from this release type: BuildCustomObjectPackageOptions */
+
+/* Excluded from this release type: BuildCustomObjectTarget */
+
+/* Excluded from this release type: BuildDiagnostic */
+
+/* Excluded from this release type: CustomObjectBuildArtifact */
+
+/* Excluded from this release type: CustomObjectBuildResult */
+
+/* Excluded from this release type: _customObjectGenerator */
+
+/* Excluded from this release type: _customObjectGenerators */
+
+/* Excluded from this release type: CustomObjectPackageBuildResult */
+
+/* Excluded from this release type: _CustomObjectParams */
+
+/* Excluded from this release type: CustomObjectPlatformMetadata */
+
+/* Excluded from this release type: CustomObjectSchemaArtifacts */
+
+/* Excluded from this release type: _customObjectsWorkspaceGenerator */
+
+/* Excluded from this release type: _CustomObjectsWorkspaceParams */
+
+/* Excluded from this release type: _customObjectTestGenerator */
+
+/* Excluded from this release type: extractCustomObjectSchemas */
+
+/* Excluded from this release type: ExtractSchemasOptions */
+
+/* Excluded from this release type: _FileWriteOutcome */
+
+/* Excluded from this release type: _Generator */
+
+/* Excluded from this release type: _GeneratorContext */
+
+/* Excluded from this release type: _GeneratorExecuteContext */
+
+/* Excluded from this release type: _GeneratorExecuteResult */
+
+/* Excluded from this release type: _GeneratorPlanResult */
+
+/* Excluded from this release type: _GeneratorRunner */
+
+/* Excluded from this release type: _GeneratorWriteResult */
+
+/* Excluded from this release type: _PlannedFile */
+
+/* Excluded from this release type: _ProjectExecuteContext */
+
+/* Excluded from this release type: _ProjectGeneratorContext */
+
+/* Excluded from this release type: _StandaloneExecuteContext */
+
+/* Excluded from this release type: _StandaloneGeneratorContext */
+
+/* Excluded from this release type: toObjectKey */
+
+/* Excluded from this release type: _WriteCapability */
+
+/* Excluded from this release type: _WriteError */
+
+export { }

package/dist/extensibility-custom-objects-tools-internal.d.ts

@@ -0,0 +1,153 @@
+/**
+ * `@stripe/extensibility-custom-objects-tools`
+ *
+ * Build-time tooling for custom object extensions: schema transformation,
+ * metadata extraction, and code generation helpers.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Metadata for a single action (method).
+ * @alpha
+ */
+export declare interface ActionMetadata {
+    /** The method name */
+    methodName: string;
+    /** String representation of argument types */
+    argType: string;
+    /** String representation of return type */
+    returnType: string;
+    /** API name for the action (defaults to snake_case of method name) */
+    apiName: string;
+}
+
+/**
+ * Actions metadata for a custom object.
+ * Only instance methods are supported — static methods cannot be actions.
+ * @alpha
+ */
+export declare interface ActionsMetadata {
+    /** Instance-level actions */
+    instance: Record<string, ActionMetadata>;
+}
+
+/**
+ * Builds the custom objects by transforming TypeScript files.
+ *
+ * @param options - Build options
+ * @returns Build result
+ * @alpha
+ */
+export declare function build(options: BuildOptions): Promise<BuildResult>;
+
+/**
+ * Options for the build process.
+ * @alpha
+ */
+export declare interface BuildOptions {
+    /** Input directory containing TypeScript source files */
+    inputDir: string;
+    /** Output directory for transformed files */
+    outputDir: string;
+    /** Whether to generate source maps (not yet implemented) */
+    sourceMap?: boolean;
+}
+
+/**
+ * Result of the entire build process.
+ * @alpha
+ */
+export declare interface BuildResult {
+    /** Results for each processed file */
+    files: FileResult[];
+    /** Any global errors */
+    errors: TransformError[];
+}
+
+/**
+ * Result of transforming a single file.
+ * @alpha
+ */
+export declare interface FileResult {
+    /** Input file path */
+    inputPath: string;
+    /** Output file path */
+    outputPath: string;
+    /** Whether the transformation succeeded */
+    success: boolean;
+    /** Any errors that occurred */
+    errors: TransformError[];
+}
+
+/**
+ * Platform metadata for a custom object class.
+ * @alpha
+ */
+export declare interface PlatformMetadata {
+    /** Module path that defined this custom object */
+    modulePath?: string;
+    /** Original TypeScript class name */
+    className?: string;
+    /** Canonical class api name */
+    classApiName?: string;
+    /** The api name of the custom object */
+    apiName: string;
+    /** All actions for this custom object */
+    actions: ActionsMetadata;
+}
+
+/**
+ * Transforms TypeScript source code with custom object decorators.
+ * Injects runtime code and extracts platform metadata.
+ *
+ * @param sourceCode - The TypeScript source code to transform
+ * @param fileName - Optional file name for error reporting
+ * @returns Transform result with code, metadata, and errors
+ * @deprecated Use `buildCustomObjectPackage` + `transformWithPlan` instead. This
+ * function performs source-only discovery without build-time schema analysis, so it
+ * cannot generate wire conversion descriptors and falls back to the legacy passthrough
+ * wrapper (no Decimal/DateTime hydration).
+ * @alpha
+ */
+export declare function transform(sourceCode: string, fileName?: string): TransformResult;
+
+/**
+ * An error that occurred during transformation.
+ * @alpha
+ */
+export declare interface TransformError {
+    /** Error message */
+    message: string;
+    /** File path (if available) */
+    file?: string;
+    /** Line number (if available) */
+    line?: number;
+    /** Column number (if available) */
+    column?: number;
+}
+
+/**
+ * Transforms a TypeScript file from disk.
+ *
+ * @param filePath - Path to the TypeScript file
+ * @returns Transform result with code, metadata, and errors
+ * @deprecated Delegates to the deprecated `transform()`. Use `buildCustomObjectPackage` instead.
+ * @alpha
+ */
+export declare function transformFile(filePath: string): Promise<TransformResult>;
+
+/**
+ * Result of transforming source code.
+ * @alpha
+ */
+export declare interface TransformResult {
+    /** Transformed source code */
+    code: string;
+    /** Platform metadata extracted from all custom objects */
+    metadata: PlatformMetadata[];
+    /** Any errors encountered during transformation */
+    errors: TransformError[];
+}
+
+export { }