@fmaplabs/meta-manifest 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -11,6 +11,10 @@ interface Config {
     apiVersion?: string;
     /** Path to the schema module whose `schemas` export drives diff/push, and pull writes. */
     schema: string;
+    /** Scope for all metaobjects, unless overridden per-metaobject. Defaults to "app". */
+    scope?: "app" | "merchant";
+    /** Default admin access for app-scoped metaobjects: false → merchant_read, true → merchant_read_write. Defaults to false. */
+    merchantEditable?: boolean;
 }
 /** Identity helper for type inference in `meta-manifest.config.ts`. */
 declare function defineConfig(config: Config): Config;
@@ -65,6 +69,14 @@ type DecodeResult<T> = {
     value?: undefined;
     issues: Issue[];
 };
+/** Options every field builder accepts, regardless of type. */
+interface CommonFieldOptions {
+    name?: string;
+    description?: string;
+    required?: boolean;
+    /** Expose this field as a filter in the admin (→ `capabilities.adminFilterable`). */
+    filterable?: boolean;
+}
 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). */
@@ -72,6 +84,9 @@ declare abstract class Field<TOut, TIn = TOut, Req extends boolean = false> {
     required: boolean;
     name?: string;
     description?: string;
+    filterable: boolean;
+    /** Apply the shared field options; call from each concrete constructor. */
+    protected applyCommon(opts: CommonFieldOptions): void;
     readonly _out: TOut;
     readonly _in: TIn;
     readonly _req: Req;
@@ -96,9 +111,7 @@ declare abstract class Field<TOut, TIn = TOut, Req extends boolean = false> {
     get ["~standard"](): StandardSchemaV1.Props<TIn, TOut>;
 }
 
-interface BooleanOptions<R extends boolean = false> {
-    name?: string;
-    description?: string;
+interface BooleanOptions<R extends boolean = false> extends CommonFieldOptions {
     required?: R;
 }
 declare class BooleanField<R extends boolean> extends Field<boolean, boolean, R> {
@@ -112,9 +125,7 @@ declare function boolean<R extends boolean = false>(opts?: BooleanOptions<R>): B
 
 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;
+interface ListOptions<R extends boolean = false> extends CommonFieldOptions {
     required?: R;
     min?: number;
     max?: number;
@@ -135,9 +146,7 @@ interface Measure {
     value: number;
     unit: string;
 }
-interface MeasureOptions<R extends boolean = false> {
-    name?: string;
-    description?: string;
+interface MeasureOptions<R extends boolean = false> extends CommonFieldOptions {
     required?: R;
 }
 declare class MeasurementField<R extends boolean> extends Field<Measure, Measure, R> {
@@ -156,9 +165,7 @@ interface Money {
     amount: string;
     currencyCode: string;
 }
-interface MoneyOptions<R extends boolean = false> {
-    name?: string;
-    description?: string;
+interface MoneyOptions<R extends boolean = false> extends CommonFieldOptions {
     required?: R;
 }
 declare class MoneyField<R extends boolean> extends Field<Money, Money, R> {
@@ -171,9 +178,7 @@ declare class MoneyField<R extends boolean> extends Field<Money, Money, R> {
 }
 declare function money<R extends boolean = false>(opts?: MoneyOptions<R>): MoneyField<R>;
 
-interface NumberOptions<R extends boolean = false> {
-    name?: string;
-    description?: string;
+interface NumberOptions<R extends boolean = false> extends CommonFieldOptions {
     required?: R;
     min?: number;
     max?: number;
@@ -212,9 +217,7 @@ interface Rating {
 interface RatingInput {
     value: number;
 }
-interface RatingOptions<R extends boolean = false> {
-    name?: string;
-    description?: string;
+interface RatingOptions<R extends boolean = false> extends CommonFieldOptions {
     required?: R;
     min: number;
     max: number;
@@ -232,9 +235,7 @@ declare class RatingField<R extends boolean> extends Field<Rating, RatingInput,
 }
 declare function rating<R extends boolean = false>(opts: RatingOptions<R>): RatingField<R>;
 
-interface RefOptions<R extends boolean = false> {
-    name?: string;
-    description?: string;
+interface RefOptions<R extends boolean = false> extends CommonFieldOptions {
     required?: R;
 }
 declare abstract class GidField<R extends boolean> extends Field<string, string, R> {
@@ -275,9 +276,7 @@ declare function page<R extends boolean = false>(opts?: RefOptions<R>): SimpleRe
 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;
+interface BaseOptions<R extends boolean = false> extends CommonFieldOptions {
     required?: R;
 }
 declare abstract class StringScalarField<R extends boolean> extends Field<string, string, R> {
@@ -323,9 +322,7 @@ declare function url<R extends boolean = false>(opts?: UrlOptions<R>): UrlField<
 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;
+interface TextOptions<R extends boolean = false> extends CommonFieldOptions {
     required?: R;
     min?: number;
     max?: number;
@@ -392,6 +389,11 @@ type InferInput<F extends FieldMap> = Simplify<{
     [K in OptionalKeys<F>]?: FieldIn<F[K]>;
 }>;
 
+interface FieldCapabilitiesInput {
+    adminFilterable?: {
+        enabled: boolean;
+    };
+}
 interface FieldDefinitionInput {
     key: string;
     name: string;
@@ -399,19 +401,44 @@ interface FieldDefinitionInput {
     required: boolean;
     type: string;
     validations: FieldValidation[];
+    capabilities?: FieldCapabilitiesInput;
+}
+interface AccessInput {
+    admin?: string;
+    storefront?: string;
+    customerAccount?: string;
+}
+interface RenderableData {
+    metaTitleKey?: string;
+    metaDescriptionKey?: string;
+}
+interface OnlineStoreData {
+    urlHandle: string;
+    createRedirects?: boolean;
+}
+interface CapabilitiesInput {
+    publishable?: {
+        enabled: boolean;
+    };
+    translatable?: {
+        enabled: boolean;
+    };
+    renderable?: {
+        enabled: boolean;
+        data?: RenderableData;
+    };
+    onlineStore?: {
+        enabled: boolean;
+        data?: OnlineStoreData;
+    };
 }
 interface MetaobjectDefinitionInput {
     type: string;
     name: string;
     description?: string;
     displayNameKey?: string;
-    access?: {
-        admin?: string;
-        storefront?: string;
-    };
-    capabilities?: Record<string, {
-        enabled: boolean;
-    }>;
+    access?: AccessInput;
+    capabilities?: CapabilitiesInput;
     fieldDefinitions: FieldDefinitionInput[];
 }
 declare function toDefinitionInput<F extends FieldMap>(schema: MetaobjectSchema<F>): MetaobjectDefinitionInput;
@@ -419,16 +446,30 @@ declare function toDefinitionInput<F extends FieldMap>(schema: MetaobjectSchema<
 interface AccessConfig {
     admin?: "merchant_read" | "merchant_read_write";
     storefront?: "public_read" | "none";
+    customerAccount?: "none" | "read";
+}
+/** SEO metadata: `true` enables with auto keys; an object maps field keys as title/description. */
+type RenderableConfig = boolean | {
+    metaTitleKey?: string;
+    metaDescriptionKey?: string;
+};
+/** Publish entries as Online Store web pages. `urlHandle` is required by Shopify. */
+interface OnlineStoreConfig {
+    urlHandle: string;
+    createRedirects?: boolean;
 }
 interface CapabilitiesConfig {
     publishable?: boolean;
     translatable?: boolean;
-    renderable?: boolean;
+    renderable?: RenderableConfig;
+    onlineStore?: OnlineStoreConfig;
 }
 interface MetaobjectConfig<F> {
     name: string;
     description?: string;
     displayName?: keyof F & string;
+    /** Override the global config scope for this metaobject. */
+    scope?: "app" | "merchant";
     access?: AccessConfig;
     capabilities?: CapabilitiesConfig;
     fields: F;
@@ -459,17 +500,54 @@ interface MetaobjectSchema<F extends FieldMap> {
 }
 declare function defineMetaobject<F extends Record<string, unknown>>(handle: string, config: MetaobjectConfig<F>): F extends FieldMap ? MetaobjectSchema<F> : never;
 
+interface RemoteAccess {
+    admin?: string;
+    storefront?: string;
+    customerAccount?: string;
+}
+/** Normalized capability comparison shape. `enabled` is compared for every capability
+ * present locally; `data` keys are compared only when locally declared. [design §8] */
+interface RemoteRenderable {
+    enabled: boolean;
+    data?: {
+        metaTitleKey?: string;
+        metaDescriptionKey?: string;
+    };
+}
+interface RemoteOnlineStore {
+    enabled: boolean;
+    data?: {
+        urlHandle?: string;
+    };
+}
+interface RemoteCapabilities {
+    publishable?: {
+        enabled: boolean;
+    };
+    translatable?: {
+        enabled: boolean;
+    };
+    renderable?: RemoteRenderable;
+    onlineStore?: RemoteOnlineStore;
+}
 interface RemoteField {
     key: string;
     type: string;
     required: boolean;
+    filterable: boolean;
     validations: FieldValidation[];
 }
 interface RemoteDefinition {
     type: string;
     name?: string;
+    description?: string;
+    displayNameKey?: string;
+    access?: RemoteAccess;
+    capabilities?: RemoteCapabilities;
     fields: RemoteField[];
 }
+/** Normalize a (already scope-resolved) definition input to the diff shape. */
+declare function normalizeDefinition(def: MetaobjectDefinitionInput): RemoteDefinition;
 declare function normalizeLocal<F extends FieldMap>(schema: MetaobjectSchema<F>): RemoteDefinition;
 interface PulledFieldDefinition {
     key: string;
@@ -478,10 +556,45 @@ interface PulledFieldDefinition {
     } | string;
     required: boolean;
     validations?: FieldValidation[];
+    capabilities?: {
+        adminFilterable?: {
+            enabled: boolean;
+        } | null;
+    } | null;
+}
+interface PulledAccess {
+    admin?: string | null;
+    storefront?: string | null;
+    customerAccount?: string | null;
+}
+interface PulledCapabilities {
+    publishable?: {
+        enabled: boolean;
+    } | null;
+    translatable?: {
+        enabled: boolean;
+    } | null;
+    renderable?: {
+        enabled: boolean;
+        data?: {
+            metaTitleKey?: string | null;
+            metaDescriptionKey?: string | null;
+        } | null;
+    } | null;
+    onlineStore?: {
+        enabled: boolean;
+        data?: {
+            urlHandle?: string | null;
+        } | null;
+    } | null;
 }
 interface PulledDefinition {
     type: string;
     name?: string;
+    description?: string | null;
+    displayNameKey?: string | null;
+    access?: PulledAccess | null;
+    capabilities?: PulledCapabilities | null;
     fieldDefinitions: PulledFieldDefinition[];
 }
 declare function normalizeRemote(def: PulledDefinition): RemoteDefinition;
@@ -493,10 +606,17 @@ declare function normalizeRemote(def: PulledDefinition): RemoteDefinition;
  */
 declare function generateSchemaSource(defs: RemoteDefinition[]): string;
 
+/** Definition-level metadata that `updateDefinition` reconciles. */
+type DefinitionChange = "name" | "description" | "displayNameKey" | "access" | "capabilities";
 type DiffOp = {
     kind: "createDefinition";
     type: string;
     definition: RemoteDefinition;
+} | {
+    kind: "updateDefinition";
+    type: string;
+    changes: DefinitionChange[];
+    destructive?: true;
 } | {
     kind: "addField";
     type: string;
@@ -521,6 +641,18 @@ type DiffOp = {
 };
 declare function diff(local: RemoteDefinition[], remote: RemoteDefinition[]): DiffOp[];
 
+type AnySchema$1 = MetaobjectSchema<any>;
+/** The subset of config that scope resolution reads. */
+type ScopeConfig = Pick<Config, "scope" | "merchantEditable">;
+type Scope = "app" | "merchant";
+/**
+ * Resolve each schema's canonical (`$app:`) definition input into the effective
+ * input the sync pipeline pushes: definition `type` and reference targets are
+ * rewritten to each metaobject's effective scope, and `access.admin` is resolved.
+ * `schema.type` / `m.ref` public values are unchanged. [design §6]
+ */
+declare function resolveDefinitions(schemas: AnySchema$1[], config?: ScopeConfig): MetaobjectDefinitionInput[];
+
 /**
  * A definition read back from the store. `type` is the canonical "$app:…" key
  * (the REQUESTED type, re-labeled from the resolved `app--…` form Shopify
@@ -599,4 +731,4 @@ declare function push(client: AdminGraphQLClient, plan: DiffOp[], sources: {
 
 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 };
+export { type AccessConfig, AdminGraphQLClient, type AnySchema, type CapabilitiesConfig, type Config, DEFAULT_API_VERSION, type DecodeResult, type DefinitionChange, 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 PulledDefinition, type PulledRemote, type PushOpResult, type PushOptions, type PushResult, type Rating, type RatingInput, type RemoteAccess, type RemoteCapabilities, type RemoteDefinition, type RemoteField, type Scope, type ScopeConfig, StandardSchemaV1, type TypeRef, defineConfig, defineMetaobject, diff, generateSchemaSource, m, normalizeDefinition, normalizeLocal, normalizeRemote, pull, pullAll, push, resolveDefinitions, toDefinitionInput, validateConfig };