@fmaplabs/meta-manifest 0.2.0 → 0.3.0

package/README.md

@@ -57,6 +57,48 @@ export const Book = defineMetaobject("book", {
 });
 ```
 
+### Configuration options
+
+Beyond fields, a metaobject definition accepts these options — all optional, all
+reconciled by `diff`/`push` against a live store:
+
+```ts
+export const Author = defineMetaobject("author", {
+  name: "Author",
+  displayName: "name",              // optional; omit → Shopify auto-generates
+  scope: "merchant",                // optional; overrides config.scope for this metaobject
+  access: {
+    admin: "merchant_read_write",   // "merchant_read" | "merchant_read_write" (app scope only)
+    storefront: "public_read",      // "none" | "public_read"
+    customerAccount: "read",        // "none" | "read"
+  },
+  capabilities: {
+    publishable: true,                                              // active/draft status
+    translatable: true,                                            // translations
+    renderable: { metaTitleKey: "name", metaDescriptionKey: "bio" }, // SEO metadata; also accepts `true`
+    onlineStore: { urlHandle: "authors", createRedirects: true },  // publish entries as web pages
+  },
+  fields: {
+    name: m.text({ required: true, filterable: true }),  // filterable → "use as filter" in the admin
+    bio: m.multilineText(),
+  },
+});
+```
+
+| Option | Maps to | Notes |
+| --- | --- | --- |
+| `scope` (config or per-metaobject) | app (`$app:<handle>`) vs merchant (`<handle>`) `type` | default `"app"`; resolved at sync time — `Author.type` stays `"$app:author"` |
+| `merchantEditable` (config) | `access.admin` default | `false` → `merchant_read`, `true` → `merchant_read_write` (app scope only) |
+| `access.admin` | `access.admin` | per-metaobject override; invalid on merchant scope |
+| `access.storefront` | `access.storefront` | Storefront API access |
+| `access.customerAccount` | `access.customerAccount` | Customer Account API access (`none` \| `read`) |
+| `capabilities.publishable` | `capabilities.publishable` | active/draft status |
+| `capabilities.translatable` | `capabilities.translatable` | translations |
+| `capabilities.renderable` | `capabilities.renderable` | `true` or `{ metaTitleKey?, metaDescriptionKey? }` (SEO) |
+| `capabilities.onlineStore` | `capabilities.onlineStore` | publish as web pages; GraphQL-only (not `shopify.app.toml`) |
+| `displayName` | `displayNameKey` | omit to let Shopify auto-generate |
+| field `filterable` | field `capabilities.adminFilterable` | expose the field as an admin filter |
+
 For the full `pull` → `diff` → `push` sync model (how local schema and a live store are
 reconciled, destructive-change gating, dependency ordering, error handling), see
 [`docs/SYNC.md`](./docs/SYNC.md).
@@ -79,6 +121,8 @@ export default defineConfig({
   accessToken: process.env.SHOPIFY_ADMIN_TOKEN!,
   apiVersion: "2026-07",           // optional; defaults to DEFAULT_API_VERSION
   schema: "./src/schema.ts",       // where `pull` writes, `diff`/`push` read
+  scope: "app",                    // optional; "app" (default) | "merchant" — applies to all metaobjects
+  merchantEditable: false,         // optional; default admin access for app-scoped metaobjects
 });
 ```
 
@@ -120,4 +164,4 @@ config/transport error, and `0` otherwise — including when destructive ops wer
 
 v1 covers metaobject **definitions** (schema sync) only. A runtime client for reading/writing
 metaobject **entries** — the tento-style query API — is not implemented yet and is tracked as a
-follow-up, along with codegen of `access`/`capabilities` config.
+follow-up.

package/dist/{chunk-PFU5VAO7.js → chunk-AUR2YQCW.js}

@@ -1,7 +1,7 @@
 import {
   DEFAULT_API_VERSION,
   SyncTransportError
-} from "./chunk-3R6VQ3Z3.js";
+} from "./chunk-VSJUGUH7.js";
 
 // src/node/client.ts
 function createAdminClient(opts) {
@@ -28,4 +28,4 @@ function createAdminClient(opts) {
 export {
   createAdminClient
 };
-//# sourceMappingURL=chunk-PFU5VAO7.js.map
+//# sourceMappingURL=chunk-AUR2YQCW.js.map

package/dist/{chunk-3R6VQ3Z3.js → chunk-VSJUGUH7.js}

@@ -28,12 +28,14 @@ var PULL_DEFINITION_QUERY = `query PullMetaobjectDefinition($type: String!) {
       required
       type { name }
       validations { name value }
+      capabilities { adminFilterable { enabled } }
     }
-    access { admin storefront }
+    access { admin storefront customerAccount }
     capabilities {
       publishable { enabled }
       translatable { enabled }
-      renderable { enabled }
+      renderable { enabled data { metaTitleKey metaDescriptionKey } }
+      onlineStore { enabled data { urlHandle } }
     }
   }
 }`;
@@ -43,6 +45,8 @@ var LIST_DEFINITIONS_QUERY = `query ListMetaobjectDefinitions($after: String) {
       id
       name
       type
+      description
+      displayNameKey
       fieldDefinitions {
         key
         name
@@ -50,6 +54,14 @@ var LIST_DEFINITIONS_QUERY = `query ListMetaobjectDefinitions($after: String) {
         required
         type { name }
         validations { name value }
+        capabilities { adminFilterable { enabled } }
+      }
+      access { admin storefront customerAccount }
+      capabilities {
+        publishable { enabled }
+        translatable { enabled }
+        renderable { enabled data { metaTitleKey metaDescriptionKey } }
+        onlineStore { enabled data { urlHandle } }
       }
     }
     pageInfo { hasNextPage endCursor }
@@ -94,4 +106,4 @@ export {
   SyncTransportError,
   execute
 };
-//# sourceMappingURL=chunk-3R6VQ3Z3.js.map
+//# sourceMappingURL=chunk-VSJUGUH7.js.map

package/dist/chunk-VSJUGUH7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts","../src/sync/client.ts"],"sourcesContent":["export const DEFAULT_API_VERSION = \"2026-07\";\n\nexport interface Config {\n  /** e.g. \"my-store.myshopify.com\" */\n  shop: string;\n  /** Admin API access token; reference via process.env in your config file. */\n  accessToken: string;\n  /** Admin API version. Defaults to DEFAULT_API_VERSION. */\n  apiVersion?: string;\n  /** Path to the schema module whose `schemas` export drives diff/push, and pull writes. */\n  schema: string;\n  /** Scope for all metaobjects, unless overridden per-metaobject. Defaults to \"app\". */\n  scope?: \"app\" | \"merchant\";\n  /** Default admin access for app-scoped metaobjects: false → merchant_read, true → merchant_read_write. Defaults to false. */\n  merchantEditable?: boolean;\n}\n\n/** Identity helper for type inference in `meta-manifest.config.ts`. */\nexport function defineConfig(config: Config): Config {\n  return config;\n}\n\n/** Validate a loaded config object, throwing a one-line Error naming the first missing field. */\nexport function validateConfig(raw: unknown): Config {\n  const c = raw as Partial<Config> | null | undefined;\n  for (const key of [\"shop\", \"accessToken\", \"schema\"] as const) {\n    if (!c || typeof c[key] !== \"string\" || c[key] === \"\") {\n      throw new Error(`Invalid config: missing or empty \"${key}\".`);\n    }\n  }\n  return c as Config;\n}\n","/**\n * The minimal Admin GraphQL transport the sync adapter depends on. The app\n * supplies a concrete implementation at its edge (wrapping `admin.graphql`),\n * keeping `@fmaplabs/meta-manifest` free of any runtime dependency on a GraphQL\n * client. [design §5]\n */\nexport interface AdminGraphQLClient {\n  (query: string, options?: { variables?: Record<string, unknown> }): Promise<{ data?: unknown; errors?: unknown }>;\n}\n\n// GraphQL operation strings, copied verbatim from the schema-validated documents\n// in the design spec §3. Re-validated against Admin API 2026-07 during planning.\n// Do not edit by hand — keep equal to the validated documents (drift guard, §12).\n\nexport const PULL_DEFINITION_QUERY = `query PullMetaobjectDefinition($type: String!) {\n  metaobjectDefinitionByType(type: $type) {\n    id\n    name\n    type\n    description\n    displayNameKey\n    fieldDefinitions {\n      key\n      name\n      description\n      required\n      type { name }\n      validations { name value }\n      capabilities { adminFilterable { enabled } }\n    }\n    access { admin storefront customerAccount }\n    capabilities {\n      publishable { enabled }\n      translatable { enabled }\n      renderable { enabled data { metaTitleKey metaDescriptionKey } }\n      onlineStore { enabled data { urlHandle } }\n    }\n  }\n}`;\n\nexport const LIST_DEFINITIONS_QUERY = `query ListMetaobjectDefinitions($after: String) {\n  metaobjectDefinitions(first: 50, after: $after) {\n    nodes {\n      id\n      name\n      type\n      description\n      displayNameKey\n      fieldDefinitions {\n        key\n        name\n        description\n        required\n        type { name }\n        validations { name value }\n        capabilities { adminFilterable { enabled } }\n      }\n      access { admin storefront customerAccount }\n      capabilities {\n        publishable { enabled }\n        translatable { enabled }\n        renderable { enabled data { metaTitleKey metaDescriptionKey } }\n        onlineStore { enabled data { urlHandle } }\n      }\n    }\n    pageInfo { hasNextPage endCursor }\n  }\n}`;\n\nexport const CREATE_DEFINITION_MUTATION = `mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n  metaobjectDefinitionCreate(definition: $definition) {\n    metaobjectDefinition { id type }\n    userErrors { field message code }\n  }\n}`;\n\nexport const UPDATE_DEFINITION_MUTATION = `mutation UpdateMetaobjectDefinition($id: ID!, $definition: MetaobjectDefinitionUpdateInput!) {\n  metaobjectDefinitionUpdate(id: $id, definition: $definition) {\n    metaobjectDefinition { id type }\n    userErrors { field message code }\n  }\n}`;\n\n/**\n * Thrown when a request fails at the transport or top-level GraphQL layer —\n * distinct from per-op `userErrors`, which `push` reports as `failed` rather\n * than throwing. Carries the offending top-level `errors` payload. [design §5]\n */\nexport class SyncTransportError extends Error {\n  constructor(message: string, readonly errors: unknown) {\n    super(message);\n    this.name = \"SyncTransportError\";\n  }\n}\n\n/**\n * Runs an operation through the injected client and returns its `data`.\n * A non-empty top-level `errors` payload becomes a `SyncTransportError`;\n * a rejected transport promise propagates unchanged. [design §5]\n */\nexport async function execute<T>(\n  client: AdminGraphQLClient,\n  query: string,\n  variables?: Record<string, unknown>,\n): Promise<T> {\n  const result = await client(query, variables ? { variables } : undefined);\n  if (Array.isArray(result.errors) ? result.errors.length > 0 : result.errors != null) {\n    throw new SyncTransportError(\"GraphQL request failed\", result.errors);\n  }\n  return result.data as T;\n}\n"],"mappings":";AAAO,IAAM,sBAAsB;AAkB5B,SAAS,aAAa,QAAwB;AACnD,SAAO;AACT;AAGO,SAAS,eAAe,KAAsB;AACnD,QAAM,IAAI;AACV,aAAW,OAAO,CAAC,QAAQ,eAAe,QAAQ,GAAY;AAC5D,QAAI,CAAC,KAAK,OAAO,EAAE,GAAG,MAAM,YAAY,EAAE,GAAG,MAAM,IAAI;AACrD,YAAM,IAAI,MAAM,qCAAqC,GAAG,IAAI;AAAA,IAC9D;AAAA,EACF;AACA,SAAO;AACT;;;ACjBO,IAAM,wBAAwB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA0B9B,IAAM,yBAAyB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA6B/B,IAAM,6BAA6B;AAAA;AAAA;AAAA;AAAA;AAAA;AAOnC,IAAM,6BAA6B;AAAA;AAAA;AAAA;AAAA;AAAA;AAYnC,IAAM,qBAAN,cAAiC,MAAM;AAAA,EAC5C,YAAY,SAA0B,QAAiB;AACrD,UAAM,OAAO;AADuB;AAEpC,SAAK,OAAO;AAAA,EACd;AAAA,EAHsC;AAIxC;AAOA,eAAsB,QACpB,QACA,OACA,WACY;AACZ,QAAM,SAAS,MAAM,OAAO,OAAO,YAAY,EAAE,UAAU,IAAI,MAAS;AACxE,MAAI,MAAM,QAAQ,OAAO,MAAM,IAAI,OAAO,OAAO,SAAS,IAAI,OAAO,UAAU,MAAM;AACnF,UAAM,IAAI,mBAAmB,0BAA0B,OAAO,MAAM;AAAA,EACtE;AACA,SAAO,OAAO;AAChB;","names":[]}