@fmaplabs/meta-manifest 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,602 @@
+import { A as AdminGraphQLClient } from './client-CdkKviW2.cjs';
+export { S as SyncTransportError } from './client-CdkKviW2.cjs';
+
+declare const DEFAULT_API_VERSION = "2026-07";
+interface Config {
+    /** e.g. "my-store.myshopify.com" */
+    shop: string;
+    /** Admin API access token; reference via process.env in your config file. */
+    accessToken: string;
+    /** Admin API version. Defaults to DEFAULT_API_VERSION. */
+    apiVersion?: string;
+    /** Path to the schema module whose `schemas` export drives diff/push, and pull writes. */
+    schema: string;
+}
+/** Identity helper for type inference in `meta-manifest.config.ts`. */
+declare function defineConfig(config: Config): Config;
+/** Validate a loaded config object, throwing a one-line Error naming the first missing field. */
+declare function validateConfig(raw: unknown): Config;
+
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+    interface Props<Input = unknown, Output = Input> {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        readonly types?: Types<Input, Output>;
+    }
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    interface SuccessResult<Output> {
+        readonly value: Output;
+        readonly issues?: undefined;
+    }
+    interface FailureResult {
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    interface Issue {
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment>;
+    }
+    interface PathSegment {
+        readonly key: PropertyKey;
+    }
+    interface Types<Input = unknown, Output = Input> {
+        readonly input: Input;
+        readonly output: Output;
+    }
+    type InferInput<S extends StandardSchemaV1> = NonNullable<S["~standard"]["types"]>["input"];
+    type InferOutput<S extends StandardSchemaV1> = NonNullable<S["~standard"]["types"]>["output"];
+}
+
+type FieldValidation = {
+    name: string;
+    value: string;
+};
+type Issue = {
+    message: string;
+    path?: PropertyKey[];
+};
+type DecodeResult<T> = {
+    value: T;
+    issues?: undefined;
+} | {
+    value?: undefined;
+    issues: Issue[];
+};
+declare abstract class Field<TOut, TIn = TOut, Req extends boolean = false> {
+    abstract readonly shopifyType: string;
+    /** True when Shopify stores this type as a JSON string (objects, lists). */
+    protected readonly wireIsJson: boolean;
+    required: boolean;
+    name?: string;
+    description?: string;
+    readonly _out: TOut;
+    readonly _in: TIn;
+    readonly _req: Req;
+    /** Shopify definition validations, e.g. [{ name: "max", value: "120" }]. */
+    abstract validations(): FieldValidation[];
+    /** Typed value -> JSON representation (number/string/object). */
+    protected abstract toJson(value: TIn): unknown;
+    /** JSON representation -> typed value (no constraint checking). */
+    protected abstract fromJson(json: unknown): DecodeResult<TOut>;
+    /** Constraint validation on an already-typed value. */
+    protected check(_value: TOut): Issue[];
+    /** Shopify wire (string or jsonValue) -> typed value (no constraint checking). */
+    coerce(wire: unknown): DecodeResult<TOut>;
+    /** Shopify wire -> typed value, validated. */
+    decode(wire: unknown): DecodeResult<TOut>;
+    /** Typed value -> Shopify wire string. */
+    encode(value: TIn): string;
+    /** Element-level JSON form (for embedding inside list values). */
+    elementToJson(value: TIn): unknown;
+    /** Element-level decode from a JSON form (coerce + check), for list elements. */
+    elementFromJson(json: unknown): DecodeResult<TOut>;
+    get ["~standard"](): StandardSchemaV1.Props<TIn, TOut>;
+}
+
+interface BooleanOptions<R extends boolean = false> {
+    name?: string;
+    description?: string;
+    required?: R;
+}
+declare class BooleanField<R extends boolean> extends Field<boolean, boolean, R> {
+    readonly shopifyType = "boolean";
+    constructor(opts: BooleanOptions<R>);
+    validations(): FieldValidation[];
+    protected toJson(value: boolean): unknown;
+    protected fromJson(json: unknown): DecodeResult<boolean>;
+}
+declare function boolean<R extends boolean = false>(opts?: BooleanOptions<R>): BooleanField<R>;
+
+type InnerOut<E> = E extends Field<infer O, any, any> ? O : never;
+type InnerIn<E> = E extends Field<any, infer I, any> ? I : never;
+interface ListOptions<R extends boolean = false> {
+    name?: string;
+    description?: string;
+    required?: R;
+    min?: number;
+    max?: number;
+}
+declare class ListField<E extends Field<any, any, any>, R extends boolean> extends Field<InnerOut<E>[], InnerIn<E>[], R> {
+    private readonly inner;
+    private readonly o;
+    readonly shopifyType: string;
+    protected readonly wireIsJson = true;
+    constructor(inner: E, o: ListOptions<R>);
+    validations(): FieldValidation[];
+    protected toJson(value: InnerIn<E>[]): unknown;
+    protected fromJson(json: unknown): DecodeResult<InnerOut<E>[]>;
+}
+declare function list<E extends Field<any, any, any>, R extends boolean = false>(inner: E, opts?: ListOptions<R>): ListField<E, R>;
+
+interface Measure {
+    value: number;
+    unit: string;
+}
+interface MeasureOptions<R extends boolean = false> {
+    name?: string;
+    description?: string;
+    required?: R;
+}
+declare class MeasurementField<R extends boolean> extends Field<Measure, Measure, R> {
+    readonly shopifyType: "dimension" | "weight" | "volume";
+    protected readonly wireIsJson = true;
+    constructor(opts: MeasureOptions<R>, shopifyType: "dimension" | "weight" | "volume");
+    validations(): FieldValidation[];
+    protected toJson(value: Measure): unknown;
+    protected fromJson(json: unknown): DecodeResult<Measure>;
+}
+declare function dimension<R extends boolean = false>(opts?: MeasureOptions<R>): MeasurementField<R>;
+declare function weight<R extends boolean = false>(opts?: MeasureOptions<R>): MeasurementField<R>;
+declare function volume<R extends boolean = false>(opts?: MeasureOptions<R>): MeasurementField<R>;
+
+interface Money {
+    amount: string;
+    currencyCode: string;
+}
+interface MoneyOptions<R extends boolean = false> {
+    name?: string;
+    description?: string;
+    required?: R;
+}
+declare class MoneyField<R extends boolean> extends Field<Money, Money, R> {
+    readonly shopifyType = "money";
+    protected readonly wireIsJson = true;
+    constructor(opts: MoneyOptions<R>);
+    validations(): FieldValidation[];
+    protected toJson(value: Money): unknown;
+    protected fromJson(json: unknown): DecodeResult<Money>;
+}
+declare function money<R extends boolean = false>(opts?: MoneyOptions<R>): MoneyField<R>;
+
+interface NumberOptions<R extends boolean = false> {
+    name?: string;
+    description?: string;
+    required?: R;
+    min?: number;
+    max?: number;
+}
+interface DecimalOptions<R extends boolean = false> extends NumberOptions<R> {
+    maxPrecision?: number;
+}
+declare abstract class NumericField<R extends boolean> extends Field<number, number, R> {
+    protected readonly opts: NumberOptions<R>;
+    constructor(opts: NumberOptions<R>);
+    protected toJson(value: number): unknown;
+    protected fromJson(json: unknown): DecodeResult<number>;
+    protected rangeIssues(value: number): Issue[];
+    protected baseValidations(): FieldValidation[];
+}
+declare class IntegerField<R extends boolean> extends NumericField<R> {
+    readonly shopifyType = "number_integer";
+    validations(): FieldValidation[];
+    protected check(value: number): Issue[];
+}
+declare class DecimalField<R extends boolean> extends NumericField<R> {
+    private readonly decimalOpts;
+    readonly shopifyType = "number_decimal";
+    constructor(decimalOpts: DecimalOptions<R>);
+    validations(): FieldValidation[];
+    protected check(value: number): Issue[];
+}
+declare function integer<R extends boolean = false>(opts?: NumberOptions<R>): IntegerField<R>;
+declare function decimal<R extends boolean = false>(opts?: DecimalOptions<R>): DecimalField<R>;
+
+interface Rating {
+    value: number;
+    scaleMin: number;
+    scaleMax: number;
+}
+interface RatingInput {
+    value: number;
+}
+interface RatingOptions<R extends boolean = false> {
+    name?: string;
+    description?: string;
+    required?: R;
+    min: number;
+    max: number;
+}
+declare class RatingField<R extends boolean> extends Field<Rating, RatingInput, R> {
+    private readonly o;
+    readonly shopifyType = "rating";
+    protected readonly wireIsJson = true;
+    constructor(o: RatingOptions<R>);
+    validations(): FieldValidation[];
+    protected toJson(value: RatingInput): unknown;
+    protected fromJson(json: unknown): DecodeResult<Rating>;
+    protected check(value: Rating): Issue[];
+    get ["~standard"](): StandardSchemaV1.Props<RatingInput, Rating>;
+}
+declare function rating<R extends boolean = false>(opts: RatingOptions<R>): RatingField<R>;
+
+interface RefOptions<R extends boolean = false> {
+    name?: string;
+    description?: string;
+    required?: R;
+}
+declare abstract class GidField<R extends boolean> extends Field<string, string, R> {
+    constructor(opts: RefOptions<R>);
+    protected toJson(value: string): unknown;
+    protected fromJson(json: unknown): DecodeResult<string>;
+}
+declare class SimpleRefField<R extends boolean> extends GidField<R> {
+    readonly shopifyType: string;
+    constructor(opts: RefOptions<R>, shopifyType: string);
+    validations(): FieldValidation[];
+}
+type FileType = "Image" | "Video";
+interface FileOptions<R extends boolean = false> extends RefOptions<R> {
+    accept?: readonly FileType[];
+}
+declare class FileField<R extends boolean> extends GidField<R> {
+    private readonly o;
+    readonly shopifyType = "file_reference";
+    constructor(o: FileOptions<R>);
+    validations(): FieldValidation[];
+}
+type TypeRef = {
+    type: string;
+} | (() => {
+    type: string;
+});
+declare class MetaobjectRefField<R extends boolean> extends GidField<R> {
+    private readonly target;
+    readonly shopifyType = "metaobject_reference";
+    constructor(target: TypeRef, opts: RefOptions<R>);
+    validations(): FieldValidation[];
+}
+declare function product<R extends boolean = false>(opts?: RefOptions<R>): SimpleRefField<R>;
+declare function variant<R extends boolean = false>(opts?: RefOptions<R>): SimpleRefField<R>;
+declare function collection<R extends boolean = false>(opts?: RefOptions<R>): SimpleRefField<R>;
+declare function page<R extends boolean = false>(opts?: RefOptions<R>): SimpleRefField<R>;
+declare function file<R extends boolean = false>(opts?: FileOptions<R>): FileField<R>;
+declare function ref<R extends boolean = false>(target: TypeRef, opts?: RefOptions<R>): MetaobjectRefField<R>;
+
+interface BaseOptions<R extends boolean = false> {
+    name?: string;
+    description?: string;
+    required?: R;
+}
+declare abstract class StringScalarField<R extends boolean> extends Field<string, string, R> {
+    constructor(opts: BaseOptions<R>);
+    protected toJson(value: string): unknown;
+    protected fromJson(json: unknown): DecodeResult<string>;
+}
+interface DateOptions<R extends boolean = false> extends BaseOptions<R> {
+    min?: string;
+    max?: string;
+}
+declare class DateField<R extends boolean> extends StringScalarField<R> {
+    private readonly o;
+    readonly shopifyType: "date" | "date_time";
+    constructor(o: DateOptions<R>, shopifyType: "date" | "date_time");
+    validations(): FieldValidation[];
+}
+interface UrlOptions<R extends boolean = false> extends BaseOptions<R> {
+    allowedDomains?: readonly string[];
+}
+declare class UrlField<R extends boolean> extends StringScalarField<R> {
+    private readonly o;
+    readonly shopifyType = "url";
+    constructor(o: UrlOptions<R>);
+    validations(): FieldValidation[];
+}
+declare class ColorField<R extends boolean> extends StringScalarField<R> {
+    readonly shopifyType = "color";
+    validations(): FieldValidation[];
+    protected check(value: string): Issue[];
+}
+declare class JsonField<R extends boolean> extends Field<unknown, unknown, R> {
+    readonly shopifyType = "json";
+    protected readonly wireIsJson = true;
+    constructor(opts: BaseOptions<R>);
+    validations(): FieldValidation[];
+    protected toJson(value: unknown): unknown;
+    protected fromJson(json: unknown): DecodeResult<unknown>;
+}
+declare function date<R extends boolean = false>(opts?: DateOptions<R>): DateField<R>;
+declare function dateTime<R extends boolean = false>(opts?: DateOptions<R>): DateField<R>;
+declare function url<R extends boolean = false>(opts?: UrlOptions<R>): UrlField<R>;
+declare function color<R extends boolean = false>(opts?: BaseOptions<R>): ColorField<R>;
+declare function json<R extends boolean = false>(opts?: BaseOptions<R>): JsonField<R>;
+
+interface TextOptions<R extends boolean = false> {
+    name?: string;
+    description?: string;
+    required?: R;
+    min?: number;
+    max?: number;
+    regex?: string;
+    choices?: readonly string[];
+}
+type MultilineOptions<R extends boolean = false> = Omit<TextOptions<R>, "choices">;
+declare class TextField<R extends boolean> extends Field<string, string, R> {
+    private readonly opts;
+    readonly shopifyType: string;
+    constructor(opts: TextOptions<R>, multiline: boolean);
+    validations(): FieldValidation[];
+    protected toJson(value: string): unknown;
+    protected fromJson(json: unknown): DecodeResult<string>;
+    protected check(value: string): Issue[];
+}
+declare function text<R extends boolean = false>(opts?: TextOptions<R>): TextField<R>;
+declare function multilineText<R extends boolean = false>(opts?: MultilineOptions<R>): TextField<R>;
+
+declare const m: {
+    readonly text: typeof text;
+    readonly multilineText: typeof multilineText;
+    readonly integer: typeof integer;
+    readonly decimal: typeof decimal;
+    readonly boolean: typeof boolean;
+    readonly date: typeof date;
+    readonly dateTime: typeof dateTime;
+    readonly url: typeof url;
+    readonly color: typeof color;
+    readonly json: typeof json;
+    readonly money: typeof money;
+    readonly dimension: typeof dimension;
+    readonly weight: typeof weight;
+    readonly volume: typeof volume;
+    readonly rating: typeof rating;
+    readonly product: typeof product;
+    readonly variant: typeof variant;
+    readonly collection: typeof collection;
+    readonly page: typeof page;
+    readonly file: typeof file;
+    readonly ref: typeof ref;
+    readonly list: typeof list;
+};
+
+type FieldMap = Record<string, Field<any, any, any>>;
+type FieldOut<T> = T extends Field<infer O, any, any> ? O : never;
+type FieldIn<T> = T extends Field<any, infer I, any> ? I : never;
+type IsRequired<T> = T extends Field<any, any, true> ? true : false;
+type RequiredKeys<F extends FieldMap> = {
+    [K in keyof F]: IsRequired<F[K]> extends true ? K : never;
+}[keyof F];
+type OptionalKeys<F extends FieldMap> = Exclude<keyof F, RequiredKeys<F>>;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type Infer<F extends FieldMap> = Simplify<{
+    [K in RequiredKeys<F>]: FieldOut<F[K]>;
+} & {
+    [K in OptionalKeys<F>]?: FieldOut<F[K]>;
+}>;
+type InferInput<F extends FieldMap> = Simplify<{
+    [K in RequiredKeys<F>]: FieldIn<F[K]>;
+} & {
+    [K in OptionalKeys<F>]?: FieldIn<F[K]>;
+}>;
+
+interface FieldDefinitionInput {
+    key: string;
+    name: string;
+    description?: string;
+    required: boolean;
+    type: string;
+    validations: FieldValidation[];
+}
+interface MetaobjectDefinitionInput {
+    type: string;
+    name: string;
+    description?: string;
+    displayNameKey?: string;
+    access?: {
+        admin?: string;
+        storefront?: string;
+    };
+    capabilities?: Record<string, {
+        enabled: boolean;
+    }>;
+    fieldDefinitions: FieldDefinitionInput[];
+}
+declare function toDefinitionInput<F extends FieldMap>(schema: MetaobjectSchema<F>): MetaobjectDefinitionInput;
+
+interface AccessConfig {
+    admin?: "merchant_read" | "merchant_read_write";
+    storefront?: "public_read" | "none";
+}
+interface CapabilitiesConfig {
+    publishable?: boolean;
+    translatable?: boolean;
+    renderable?: boolean;
+}
+interface MetaobjectConfig<F> {
+    name: string;
+    description?: string;
+    displayName?: keyof F & string;
+    access?: AccessConfig;
+    capabilities?: CapabilitiesConfig;
+    fields: F;
+}
+type ParseInput = ReadonlyArray<{
+    key: string;
+    jsonValue?: unknown;
+    value?: unknown;
+}> | Record<string, unknown>;
+interface MetaobjectSchema<F extends FieldMap> {
+    readonly handle: string;
+    readonly type: string;
+    readonly config: MetaobjectConfig<F>;
+    readonly fields: F;
+    parse(input: ParseInput): {
+        value: Infer<F>;
+        issues?: undefined;
+    } | {
+        value?: undefined;
+        issues: Issue[];
+    };
+    encode(value: InferInput<F>): Array<{
+        key: string;
+        value: string;
+    }>;
+    toDefinitionInput(): MetaobjectDefinitionInput;
+    readonly ["~standard"]: StandardSchemaV1.Props<InferInput<F>, Infer<F>>;
+}
+declare function defineMetaobject<F extends Record<string, unknown>>(handle: string, config: MetaobjectConfig<F>): F extends FieldMap ? MetaobjectSchema<F> : never;
+
+interface RemoteField {
+    key: string;
+    type: string;
+    required: boolean;
+    validations: FieldValidation[];
+}
+interface RemoteDefinition {
+    type: string;
+    name?: string;
+    fields: RemoteField[];
+}
+declare function normalizeLocal<F extends FieldMap>(schema: MetaobjectSchema<F>): RemoteDefinition;
+interface PulledFieldDefinition {
+    key: string;
+    type: {
+        name: string;
+    } | string;
+    required: boolean;
+    validations?: FieldValidation[];
+}
+interface PulledDefinition {
+    type: string;
+    name?: string;
+    fieldDefinitions: PulledFieldDefinition[];
+}
+declare function normalizeRemote(def: PulledDefinition): RemoteDefinition;
+
+/**
+ * Generate `schema.ts` source (using `defineMetaobject`/`m`) from remote definitions.
+ * Definitions are emitted in dependency order so `m.ref(...)` points at a declared const.
+ * Unmapped types/validations become `// TODO: unmapped …` and are logged via console.warn.
+ */
+declare function generateSchemaSource(defs: RemoteDefinition[]): string;
+
+type DiffOp = {
+    kind: "createDefinition";
+    type: string;
+    definition: RemoteDefinition;
+} | {
+    kind: "addField";
+    type: string;
+    field: RemoteField;
+} | {
+    kind: "updateField";
+    type: string;
+    key: string;
+    changes: Partial<RemoteField>;
+} | {
+    kind: "changeFieldType";
+    type: string;
+    key: string;
+    from: string;
+    to: string;
+    destructive: true;
+} | {
+    kind: "removeField";
+    type: string;
+    key: string;
+    destructive: true;
+};
+declare function diff(local: RemoteDefinition[], remote: RemoteDefinition[]): DiffOp[];
+
+/**
+ * A definition read back from the store. `type` is the canonical "$app:…" key
+ * (the REQUESTED type, re-labeled from the resolved `app--…` form Shopify
+ * returns) so `diff()` matches local↔remote; `id` is the GID `push` threads into
+ * update ops. [design §6]
+ */
+interface PulledRemote {
+    id: string;
+    type: string;
+    definition: PulledDefinition;
+}
+/**
+ * Reads the current metaobject definitions for the given `$app:` types. A type
+ * absent from the store is omitted (so `diff()` emits a create). Each present
+ * node is re-labeled with the requested type and its `id` is captured. [design §6]
+ */
+declare function pull(client: AdminGraphQLClient, types: readonly string[]): Promise<PulledRemote[]>;
+/**
+ * Enumerate every metaobject definition in the store. By default returns only
+ * app-owned definitions, re-labeled to canonical "$app:<handle>" types so they
+ * round-trip through `defineMetaobject`. [design §3]
+ */
+declare function pullAll(client: AdminGraphQLClient, opts?: {
+    appOwnedOnly?: boolean;
+}): Promise<PulledRemote[]>;
+
+interface PushOptions {
+    /** Apply destructive ops (`removeField`, `changeFieldType`). Default false. */
+    allowDestructive?: boolean;
+}
+type PushOpResult = {
+    op: DiffOp;
+    status: "applied";
+    id?: string;
+} | {
+    op: DiffOp;
+    status: "skipped";
+    reason: "destructive";
+} | {
+    op: DiffOp;
+    status: "blocked";
+    reason: string;
+} | {
+    op: DiffOp;
+    status: "failed";
+    userErrors: UserError[];
+};
+interface PushResult {
+    results: PushOpResult[];
+    counts: {
+        applied: number;
+        skipped: number;
+        blocked: number;
+        failed: number;
+    };
+    ok: boolean;
+}
+type UserError = {
+    field?: string[];
+    message: string;
+    code?: string;
+};
+/**
+ * Applies a `diff()` plan to a store. Safe ops run; destructive ops are skipped
+ * unless `allowDestructive`. Per-op `userErrors` become `failed` entries (never
+ * thrown); only transport / top-level GraphQL errors propagate. [design §7, §8]
+ *
+ * Create ops run in dependency order (a referenced type before its referencer);
+ * types in a reference cycle are `blocked`. Results are returned in plan order;
+ * client calls happen in execution order. [design §7]
+ */
+declare function push(client: AdminGraphQLClient, plan: DiffOp[], sources: {
+    definitions: MetaobjectDefinitionInput[];
+    remote: PulledRemote[];
+}, options?: PushOptions): Promise<PushResult>;
+
+type AnySchema = MetaobjectSchema<any>;
+
+export { type AccessConfig, AdminGraphQLClient, type AnySchema, type CapabilitiesConfig, type Config, DEFAULT_API_VERSION, type DecodeResult, type DiffOp, Field, type FieldDefinitionInput, type FieldValidation, type FileType, type Infer, type InferInput, type Issue, type Measure, type MetaobjectConfig, type MetaobjectDefinitionInput, type MetaobjectSchema, type Money, type ParseInput, type PulledRemote, type PushOpResult, type PushOptions, type PushResult, type Rating, type RatingInput, type RemoteDefinition, type RemoteField, StandardSchemaV1, type TypeRef, defineConfig, defineMetaobject, diff, generateSchemaSource, m, normalizeLocal, normalizeRemote, pull, pullAll, push, toDefinitionInput, validateConfig };