@tryghost/metafield-types 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013-2026 Ghost Foundation
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @tryghost/metafield-types
+
+The types of member custom field Ghost supports: which types exist, which parts a
+type is made of, the type of value each part holds, and how a value of each type is
+validated. Ghost, its Admin and Portal use it, and so can an integration that offers
+inputs for a site's custom fields, such as the Ghost Zapier integration.
+
+```bash
+npm install @tryghost/metafield-types
+```
+
+## Entry points
+
+- `@tryghost/metafield-types/structure`: the type ids, each type's parts and the
+  type of value each part holds. It depends on nothing.
+- `@tryghost/metafield-types/countries`: the two-letter country codes a country
+  part accepts. It depends on nothing.
+- `@tryghost/metafield-types/identity`: how a field is named in filters and
+  payloads (`custom.<key>`). It depends on nothing.
+- `@tryghost/metafield-types`: the structure above, plus the rules that validate
+  a value of each type. These are built on [zod](https://zod.dev), and only this
+  entry point loads it, so an integration that only draws inputs can use the three
+  entry points above without zod ever being loaded.
+
+## Compatibility
+
+An integration using this package talks to sites on many Ghost versions, so a type
+never changes once it has shipped: it keeps its parts and the type of value each
+holds. New structure arrives as a new type. An integration should skip a type it
+doesn't recognise, which is what happens when a site is on a newer Ghost than the
+package the integration was built with.
+
+## Develop
+
+This is a workspace package in the Ghost monorepo. From the repo root:
+
+```bash
+pnpm --filter @tryghost/metafield-types build   # compile to build/ with tsc (ESM)
+pnpm --filter @tryghost/metafield-types test    # type-check + unit tests
+pnpm --filter @tryghost/metafield-types dev     # rebuild on change
+```
+
+In-monorepo consumers resolve this package via the `source` export condition
+(raw `src/*.ts`, no build needed in dev/test). Production and any published
+tarball use the compiled `build/` output.
+
+This package is ESM-only and compiled with `tsc` (`module: nodenext`). Relative
+imports in `src/` must carry an explicit extension; write the real `.ts` one —
+`import {x} from './x.ts'` — and `tsc` rewrites it to `.js` on emit
+(`rewriteRelativeImportExtensions`).
+
+`./structure` is the half of the catalog a renderer needs — which parts a field type
+has, and what each holds — and it stands apart from `./index` so that importing it
+costs a bundle almost nothing. The rules in `./index` are built on zod, some
+seventeen kilobytes gzipped that a renderer never runs. Portal imports `./structure`
+and loads on every page view of every themed site, so the difference reaches every
+visitor of every Ghost site.
+
+That holds only while `./structure` depends on nothing, and no bundler enforces it: an
+import added here would ship to every one of those visitors with every check still
+green. So **`src/structure.ts` must not import anything** — an ESLint rule enforces
+it, relative imports included, since anything reached through one is bundled too.
+Whatever needs an import belongs in `./index`, which is free to use them.
+
+`ghost/core` is CommonJS but consumes this package via `require()`, which works
+on Ghost's Node version (22.13+/24) through Node's `require(esm)` support. That
+support has one hard constraint: **no top-level `await`** anywhere in this
+package's module graph — it makes the graph async and `require()` of it throws
+`ERR_REQUIRE_ASYNC_MODULE`. Keep module-level initialization synchronous. (An
+ESLint rule enforces this.)

package/build/countries.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Every ISO 3166-1 country an address may name, as two-letter codes.
+ *
+ * Here because both renderers of an address need the same list and cannot import each
+ * other's: Admin's picker and Portal's select must offer the same countries, or a member
+ * could record one staff cannot read back. Codes only, no names: a browser names a
+ * region in the reader's language through `Intl.DisplayNames`, and a bundled name list
+ * would be English and stale. Kosovo (XK) is here as the one user-assigned code in
+ * common use, and Ascension Island (AC) and Tristan da Cunha (TA) as the exceptionally
+ * reserved codes real addresses use, which Stripe ships to and a checkout can store.
+ */
+export declare const COUNTRY_CODES: readonly ['AC', 'AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AO', 'AQ', 'AR', 'AS', 'AT', 'AU', 'AW', 'AX', 'AZ', 'BA', 'BB', 'BD', 'BE', 'BF', 'BG', 'BH', 'BI', 'BJ', 'BL', 'BM', 'BN', 'BO', 'BQ', 'BR', 'BS', 'BT', 'BV', 'BW', 'BY', 'BZ', 'CA', 'CC', 'CD', 'CF', 'CG', 'CH', 'CI', 'CK', 'CL', 'CM', 'CN', 'CO', 'CR', 'CU', 'CV', 'CW', 'CX', 'CY', 'CZ', 'DE', 'DJ', 'DK', 'DM', 'DO', 'DZ', 'EC', 'EE', 'EG', 'EH', 'ER', 'ES', 'ET', 'FI', 'FJ', 'FK', 'FM', 'FO', 'FR', 'GA', 'GB', 'GD', 'GE', 'GF', 'GG', 'GH', 'GI', 'GL', 'GM', 'GN', 'GP', 'GQ', 'GR', 'GS', 'GT', 'GU', 'GW', 'GY', 'HK', 'HM', 'HN', 'HR', 'HT', 'HU', 'ID', 'IE', 'IL', 'IM', 'IN', 'IO', 'IQ', 'IR', 'IS', 'IT', 'JE', 'JM', 'JO', 'JP', 'KE', 'KG', 'KH', 'KI', 'KM', 'KN', 'KP', 'KR', 'KW', 'KY', 'KZ', 'LA', 'LB', 'LC', 'LI', 'LK', 'LR', 'LS', 'LT', 'LU', 'LV', 'LY', 'MA', 'MC', 'MD', 'ME', 'MF', 'MG', 'MH', 'MK', 'ML', 'MM', 'MN', 'MO', 'MP', 'MQ', 'MR', 'MS', 'MT', 'MU', 'MV', 'MW', 'MX', 'MY', 'MZ', 'NA', 'NC', 'NE', 'NF', 'NG', 'NI', 'NL', 'NO', 'NP', 'NR', 'NU', 'NZ', 'OM', 'PA', 'PE', 'PF', 'PG', 'PH', 'PK', 'PL', 'PM', 'PN', 'PR', 'PS', 'PT', 'PW', 'PY', 'QA', 'RE', 'RO', 'RS', 'RU', 'RW', 'SA', 'SB', 'SC', 'SD', 'SE', 'SG', 'SH', 'SI', 'SJ', 'SK', 'SL', 'SM', 'SN', 'SO', 'SR', 'SS', 'ST', 'SV', 'SX', 'SY', 'SZ', 'TA', 'TC', 'TD', 'TF', 'TG', 'TH', 'TJ', 'TK', 'TL', 'TM', 'TN', 'TO', 'TR', 'TT', 'TV', 'TW', 'TZ', 'UA', 'UG', 'UM', 'US', 'UY', 'UZ', 'VA', 'VC', 'VE', 'VG', 'VI', 'VN', 'VU', 'WF', 'WS', 'XK', 'YE', 'YT', 'ZA', 'ZM', 'ZW'];
+export type CountryCode = (typeof COUNTRY_CODES)[number];
+//# sourceMappingURL=countries.d.ts.map

package/build/countries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"countries.d.ts","sourceRoot":"","sources":["../src/countries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,YACxB,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,CACI,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/build/countries.js

@@ -0,0 +1,266 @@
+/**
+ * Every ISO 3166-1 country an address may name, as two-letter codes.
+ *
+ * Here because both renderers of an address need the same list and cannot import each
+ * other's: Admin's picker and Portal's select must offer the same countries, or a member
+ * could record one staff cannot read back. Codes only, no names: a browser names a
+ * region in the reader's language through `Intl.DisplayNames`, and a bundled name list
+ * would be English and stale. Kosovo (XK) is here as the one user-assigned code in
+ * common use, and Ascension Island (AC) and Tristan da Cunha (TA) as the exceptionally
+ * reserved codes real addresses use, which Stripe ships to and a checkout can store.
+ */
+export const COUNTRY_CODES = [
+    'AC',
+    'AD',
+    'AE',
+    'AF',
+    'AG',
+    'AI',
+    'AL',
+    'AM',
+    'AO',
+    'AQ',
+    'AR',
+    'AS',
+    'AT',
+    'AU',
+    'AW',
+    'AX',
+    'AZ',
+    'BA',
+    'BB',
+    'BD',
+    'BE',
+    'BF',
+    'BG',
+    'BH',
+    'BI',
+    'BJ',
+    'BL',
+    'BM',
+    'BN',
+    'BO',
+    'BQ',
+    'BR',
+    'BS',
+    'BT',
+    'BV',
+    'BW',
+    'BY',
+    'BZ',
+    'CA',
+    'CC',
+    'CD',
+    'CF',
+    'CG',
+    'CH',
+    'CI',
+    'CK',
+    'CL',
+    'CM',
+    'CN',
+    'CO',
+    'CR',
+    'CU',
+    'CV',
+    'CW',
+    'CX',
+    'CY',
+    'CZ',
+    'DE',
+    'DJ',
+    'DK',
+    'DM',
+    'DO',
+    'DZ',
+    'EC',
+    'EE',
+    'EG',
+    'EH',
+    'ER',
+    'ES',
+    'ET',
+    'FI',
+    'FJ',
+    'FK',
+    'FM',
+    'FO',
+    'FR',
+    'GA',
+    'GB',
+    'GD',
+    'GE',
+    'GF',
+    'GG',
+    'GH',
+    'GI',
+    'GL',
+    'GM',
+    'GN',
+    'GP',
+    'GQ',
+    'GR',
+    'GS',
+    'GT',
+    'GU',
+    'GW',
+    'GY',
+    'HK',
+    'HM',
+    'HN',
+    'HR',
+    'HT',
+    'HU',
+    'ID',
+    'IE',
+    'IL',
+    'IM',
+    'IN',
+    'IO',
+    'IQ',
+    'IR',
+    'IS',
+    'IT',
+    'JE',
+    'JM',
+    'JO',
+    'JP',
+    'KE',
+    'KG',
+    'KH',
+    'KI',
+    'KM',
+    'KN',
+    'KP',
+    'KR',
+    'KW',
+    'KY',
+    'KZ',
+    'LA',
+    'LB',
+    'LC',
+    'LI',
+    'LK',
+    'LR',
+    'LS',
+    'LT',
+    'LU',
+    'LV',
+    'LY',
+    'MA',
+    'MC',
+    'MD',
+    'ME',
+    'MF',
+    'MG',
+    'MH',
+    'MK',
+    'ML',
+    'MM',
+    'MN',
+    'MO',
+    'MP',
+    'MQ',
+    'MR',
+    'MS',
+    'MT',
+    'MU',
+    'MV',
+    'MW',
+    'MX',
+    'MY',
+    'MZ',
+    'NA',
+    'NC',
+    'NE',
+    'NF',
+    'NG',
+    'NI',
+    'NL',
+    'NO',
+    'NP',
+    'NR',
+    'NU',
+    'NZ',
+    'OM',
+    'PA',
+    'PE',
+    'PF',
+    'PG',
+    'PH',
+    'PK',
+    'PL',
+    'PM',
+    'PN',
+    'PR',
+    'PS',
+    'PT',
+    'PW',
+    'PY',
+    'QA',
+    'RE',
+    'RO',
+    'RS',
+    'RU',
+    'RW',
+    'SA',
+    'SB',
+    'SC',
+    'SD',
+    'SE',
+    'SG',
+    'SH',
+    'SI',
+    'SJ',
+    'SK',
+    'SL',
+    'SM',
+    'SN',
+    'SO',
+    'SR',
+    'SS',
+    'ST',
+    'SV',
+    'SX',
+    'SY',
+    'SZ',
+    'TA',
+    'TC',
+    'TD',
+    'TF',
+    'TG',
+    'TH',
+    'TJ',
+    'TK',
+    'TL',
+    'TM',
+    'TN',
+    'TO',
+    'TR',
+    'TT',
+    'TV',
+    'TW',
+    'TZ',
+    'UA',
+    'UG',
+    'UM',
+    'US',
+    'UY',
+    'UZ',
+    'VA',
+    'VC',
+    'VE',
+    'VG',
+    'VI',
+    'VN',
+    'VU',
+    'WF',
+    'WS',
+    'XK',
+    'YE',
+    'YT',
+    'ZA',
+    'ZM',
+    'ZW',
+];
+//# sourceMappingURL=countries.js.map

package/build/countries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"countries.js","sourceRoot":"","sources":["../src/countries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;CACI,CAAC"}

package/build/csv.d.ts

@@ -0,0 +1,39 @@
+import { type FieldType } from './index.ts';
+import type { FieldIdentityString } from './identity.ts';
+/** A field definition reduced to what CSV needs to know about it. */
+export interface CsvField {
+    namespace: string;
+    key: string;
+    type: FieldType;
+}
+/** A column a field occupies, and which part of the field's value it holds. */
+export interface CsvFieldColumn {
+    column: string;
+    /** The part this column holds, or null where the field's whole value is one column. */
+    subField: string | null;
+}
+export declare function csvColumnsForField(field: CsvField): CsvFieldColumn[];
+export declare function isMetafieldColumn(column: string): boolean;
+export declare function csvCellsForFields(fields: readonly CsvField[], values: Record<string, Record<string, unknown> | undefined>): Record<string, string>;
+/**
+ * The inverse of `csvCellsForFields`: read a row's metafield cells into the values a
+ * member write takes. Only the passed fields are read, so a column naming no active
+ * field is dropped rather than erroring.
+ *
+ * `decodeCell` turns a raw cell into its value; it defaults to identity. The caller owns
+ * any de-serialization the specific file needs — the members importer passes one that
+ * strips the export's formula guard — so this stays pure vocabulary and holds no knowledge
+ * of how any particular CSV escapes its cells.
+ *
+ * A field is written only from a non-blank cell; a blank or absent cell leaves the
+ * existing value untouched, not cleared — matching how the importer keeps a blank name or
+ * note, so re-importing a partly-filled export can't wipe values a publisher didn't
+ * touch. A composite whose every cell is blank is omitted too, because the export writes
+ * "no address" and an all-blank address identically; one with any filled cell is read
+ * from its non-blank cells and validated whole (a malformed sub-field fails the row).
+ * No sub-field is required, so a row carrying only some of an address reads as only
+ * those sub-fields. A blank sub-field cell reads as no data for that sub-field, the
+ * same way a blank cell reads as no data for a whole field.
+ */
+export declare function fieldValuesFromCsvRow(fields: readonly CsvField[], row: Record<string, unknown>, decodeCell?: (cell: string) => string): Record<FieldIdentityString, unknown>;
+//# sourceMappingURL=csv.d.ts.map

package/build/csv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../src/csv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAqBzD,qEAAqE;AACrE,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,SAAS,CAAC;CACjB;AAcD,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,uFAAuF;IACvF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAID,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,GAAG,cAAc,EAAE,CAMpE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AAeD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,QAAQ,EAAE,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,GAC1D,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoBxB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,QAAQ,EAAE,EAC3B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,UAAU,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAuB,GACpD,MAAM,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAqCtC"}

package/build/csv.js

@@ -0,0 +1,119 @@
+import { subFieldsOf } from './index.js';
+import { QUALIFIER, SEPARATOR, formatIdentity } from './identity.js';
+/**
+ * How a field's value maps onto CSV columns.
+ *
+ * CSV is flat and a value need not be, so a composite occupies one column per
+ * sub-field. That shape is derived from the type's own value schema rather than
+ * declared alongside it: the two cannot drift, and it stays correct as sub-fields
+ * are added, removed, or made optional — an optional sub-field is still a column,
+ * it just holds an empty cell more often.
+ *
+ * The same column names are the vocabulary the importer maps onto, so an exported
+ * file re-imports without the publisher remapping anything by hand.
+ */
+const PREFIX = `${QUALIFIER}${SEPARATOR}`;
+function columnIdentity(field) {
+    return formatIdentity({ namespace: field.namespace, key: field.key, partPath: null });
+}
+function toCell(value) {
+    return value === undefined || value === null ? '' : String(value);
+}
+// A cell holding nothing but whitespace carries no more data than an empty one, so both
+// read as blank. Without this a stray space is a value: it would be stored as one on a
+// scalar, and on a composite it would make an otherwise untouched address fail its "at
+// least one part filled in" rule and take the whole member row down with it.
+function isBlank(cell) {
+    return cell.trim() === '';
+}
+// Shares csvCellsForFields' column derivation, so a field is written, read, and offered
+// as a mapping target under one set of column names.
+export function csvColumnsForField(field) {
+    const column = `${PREFIX}${columnIdentity(field)}`;
+    const subFields = subFieldsOf(field.type);
+    return subFields
+        ? subFields.map((sub) => ({ column: `${column}${SEPARATOR}${sub}`, subField: sub }))
+        : [{ column, subField: null }];
+}
+export function isMetafieldColumn(column) {
+    return column === QUALIFIER || column.startsWith(PREFIX);
+}
+// A missing column and a column present but blank mean different things here, so
+// presence has to be detectable. The CSV parser only ever puts strings in these
+// cells, which makes "not a string" a reliable stand-in for "no such column".
+function cellFor(row, field, tail) {
+    const suffix = tail === null ? '' : `${SEPARATOR}${tail}`;
+    const cell = row[`${PREFIX}${columnIdentity(field)}${suffix}`];
+    return typeof cell === 'string' ? cell : undefined;
+}
+export function csvCellsForFields(fields, values) {
+    const cells = {};
+    for (const field of fields) {
+        const value = values[field.namespace]?.[field.key];
+        const subFields = subFieldsOf(field.type);
+        const column = `${PREFIX}${columnIdentity(field)}`;
+        if (!subFields) {
+            cells[column] = toCell(value);
+            continue;
+        }
+        const composite = (value ?? {});
+        for (const sub of subFields) {
+            cells[`${column}${SEPARATOR}${sub}`] = toCell(composite[sub]);
+        }
+    }
+    return cells;
+}
+/**
+ * The inverse of `csvCellsForFields`: read a row's metafield cells into the values a
+ * member write takes. Only the passed fields are read, so a column naming no active
+ * field is dropped rather than erroring.
+ *
+ * `decodeCell` turns a raw cell into its value; it defaults to identity. The caller owns
+ * any de-serialization the specific file needs — the members importer passes one that
+ * strips the export's formula guard — so this stays pure vocabulary and holds no knowledge
+ * of how any particular CSV escapes its cells.
+ *
+ * A field is written only from a non-blank cell; a blank or absent cell leaves the
+ * existing value untouched, not cleared — matching how the importer keeps a blank name or
+ * note, so re-importing a partly-filled export can't wipe values a publisher didn't
+ * touch. A composite whose every cell is blank is omitted too, because the export writes
+ * "no address" and an all-blank address identically; one with any filled cell is read
+ * from its non-blank cells and validated whole (a malformed sub-field fails the row).
+ * No sub-field is required, so a row carrying only some of an address reads as only
+ * those sub-fields. A blank sub-field cell reads as no data for that sub-field, the
+ * same way a blank cell reads as no data for a whole field.
+ */
+export function fieldValuesFromCsvRow(fields, row, decodeCell = (cell) => cell) {
+    const values = {};
+    for (const field of fields) {
+        const subFields = subFieldsOf(field.type);
+        if (!subFields) {
+            const cell = cellFor(row, field, null);
+            if (cell !== undefined) {
+                const decoded = decodeCell(cell);
+                if (!isBlank(decoded)) {
+                    values[columnIdentity(field)] = decoded;
+                }
+            }
+            continue;
+        }
+        let anyColumnPresent = false;
+        const composite = {};
+        for (const sub of subFields) {
+            const cell = cellFor(row, field, sub);
+            if (cell === undefined) {
+                continue;
+            }
+            anyColumnPresent = true;
+            const decoded = decodeCell(cell);
+            if (!isBlank(decoded)) {
+                composite[sub] = decoded;
+            }
+        }
+        if (anyColumnPresent && Object.keys(composite).length > 0) {
+            values[columnIdentity(field)] = composite;
+        }
+    }
+    return values;
+}
+//# sourceMappingURL=csv.js.map

package/build/csv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.js","sourceRoot":"","sources":["../src/csv.ts"],"names":[],"mappings":"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"}

package/build/identity.d.ts

@@ -0,0 +1,36 @@
+/**
+ * How a field is named on every surface that writes its name down as text: CSV column
+ * headers, filter values, error paths, URLs.
+ *
+ * The name is the namespace that declared the field and the field's key, joined by a
+ * dot — `custom.company`. A value made of several parts, such as an address, appends
+ * the part: `custom.shipping_address.country`. Splitting on dots by position is safe
+ * because a key can never contain one; that is enforced where keys are minted.
+ *
+ * `metafields` is the qualifier, not part of the identity: it names the container, and
+ * each context writes it exactly once — the payload key, the route prefix, the CSV
+ * column prefix, the filter relation alias — never twice.
+ */
+export declare const QUALIFIER = "metafields";
+export declare const SEPARATOR = ".";
+/**
+ * The namespace holding the fields a site's own staff define.
+ *
+ * It is a constant only because the table storing these fields has no namespace
+ * column: it holds this namespace's fields and nothing else, so the query layer has
+ * to supply the name the rows implicitly carry. Nothing outside that layer should
+ * compare against this value — a namespace nobody has declared fields in is an empty
+ * namespace, not an error.
+ */
+export declare const CUSTOM_NAMESPACE = "custom";
+export declare const IDENTITY_SEGMENT: RegExp;
+/** A formatted identity — `namespace.key`, or `namespace.key.partPath` for one part. */
+export type FieldIdentityString = string;
+export interface FieldIdentity {
+    namespace: string;
+    key: string;
+    partPath: string | null;
+}
+export declare function formatIdentity({ namespace, key, partPath }: FieldIdentity): FieldIdentityString;
+export declare function parseIdentity(identity: string): FieldIdentity | null;
+//# sourceMappingURL=identity.d.ts.map

package/build/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,SAAS,eAAe,CAAC;AAEtC,eAAO,MAAM,SAAS,MAAM,CAAC;AAE7B;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,WAAW,CAAC;AAEzC,eAAO,MAAM,gBAAgB,QAAiB,CAAC;AAE/C,wFAAwF;AACxF,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,wBAAgB,cAAc,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,aAAa,GAAG,mBAAmB,CAG/F;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAUpE"}

package/build/identity.js

@@ -0,0 +1,40 @@
+/**
+ * How a field is named on every surface that writes its name down as text: CSV column
+ * headers, filter values, error paths, URLs.
+ *
+ * The name is the namespace that declared the field and the field's key, joined by a
+ * dot — `custom.company`. A value made of several parts, such as an address, appends
+ * the part: `custom.shipping_address.country`. Splitting on dots by position is safe
+ * because a key can never contain one; that is enforced where keys are minted.
+ *
+ * `metafields` is the qualifier, not part of the identity: it names the container, and
+ * each context writes it exactly once — the payload key, the route prefix, the CSV
+ * column prefix, the filter relation alias — never twice.
+ */
+export const QUALIFIER = 'metafields';
+export const SEPARATOR = '.';
+/**
+ * The namespace holding the fields a site's own staff define.
+ *
+ * It is a constant only because the table storing these fields has no namespace
+ * column: it holds this namespace's fields and nothing else, so the query layer has
+ * to supply the name the rows implicitly carry. Nothing outside that layer should
+ * compare against this value — a namespace nobody has declared fields in is an empty
+ * namespace, not an error.
+ */
+export const CUSTOM_NAMESPACE = 'custom';
+export const IDENTITY_SEGMENT = /^[a-z0-9_]+$/;
+export function formatIdentity({ namespace, key, partPath }) {
+    const identity = `${namespace}${SEPARATOR}${key}`;
+    return partPath ? `${identity}${SEPARATOR}${partPath}` : identity;
+}
+export function parseIdentity(identity) {
+    const [namespace, key, ...parts] = identity.split(SEPARATOR);
+    if (namespace === undefined ||
+        key === undefined ||
+        ![namespace, key, ...parts].every((segment) => IDENTITY_SEGMENT.test(segment))) {
+        return null;
+    }
+    return { namespace, key, partPath: parts.length > 0 ? parts.join(SEPARATOR) : null };
+}
+//# sourceMappingURL=identity.js.map

package/build/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,SAAS,GAAG,YAAY,CAAC;AAEtC,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,CAAC;AAEzC,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,CAAC;AAW/C,MAAM,UAAU,cAAc,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAiB;IACxE,MAAM,QAAQ,GAAG,GAAG,SAAS,GAAG,SAAS,GAAG,GAAG,EAAE,CAAC;IAClD,OAAO,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,MAAM,CAAC,SAAS,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC7D,IACE,SAAS,KAAK,SAAS;QACvB,GAAG,KAAK,SAAS;QACjB,CAAC,CAAC,SAAS,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAC9E,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACvF,CAAC"}

package/build/index.d.ts

@@ -0,0 +1,175 @@
+import { z } from 'zod';
+import { type FieldType } from './structure.js';
+export { FIELD_KINDS, FIELD_PARTS, FIELD_TYPE_IDS, PART_TYPE_IDS, partTypesOf, subFieldsOf, type FieldKind, type FieldType, type PartsOf, type PartType, } from './structure.js';
+/**
+ * The shared catalog of member metafield types.
+ *
+ * ## What a field type is
+ *
+ * A publisher defines fields; a field has a type; a type says what a valid value is. That
+ * last statement lives here and nowhere else, so that Ghost core, which enforces it, and
+ * admin, which gives instant feedback against it, cannot disagree about what is valid.
+ *
+ * A type is one of two things. Most are a value in their own right, declared as the
+ * schema that value must satisfy. An address is a *record*: a set of named parts, each a
+ * value in the same sense, from which the whole type's schema is derived. Nothing stops a
+ * part being a record itself.
+ *
+ * ## What a write may say
+ *
+ * A value is text, and so is every part of one. A write names what it means to change: a
+ * name it does not mention is left as it was, and a name given an empty string is being
+ * cleared. That is why every part accepts empty regardless of its own rule — emptying is
+ * a statement about the write, not about the part.
+ *
+ * A name nobody recognizes is an error rather than a silent drop, at both depths. A
+ * misspelled field key is refused by the values service, which alone knows which fields a
+ * site has defined; a misspelled part is refused here, because a type's parts are declared
+ * in this file and nowhere else. Each is enforced where the names are known.
+ *
+ * ## What a failure says
+ *
+ * A rule carries the sentence shown when it is broken, so the two cannot drift. Each
+ * states what is expected rather than what went wrong, so one sentence covers every way
+ * of breaking that rule.
+ *
+ * The sentences are plain literals with no interpolation, so each is usable as a
+ * translation key. Nothing here translates: Ghost's parser reads `t()` calls out of the
+ * app that renders a string, so that app owns the step. Admin, the only one today, is not
+ * translated at all.
+ *
+ * Two failures keep zod's own wording, both reachable only by a client sending the wrong
+ * JSON shape: a composite handed something that is not an object, and a part nobody
+ * declared. Naming the offending key serves whoever has to fix that client.
+ *
+ * ## What this package will not do
+ *
+ * No presentation beyond that sentence: labels, icons and input controls belong to the
+ * frontend, and so does any wording that depends on where it appears rather than on which
+ * rule was broken. No storage: columns and codecs belong to the backend. One exception
+ * lives in `./csv` — how a value maps onto CSV columns — because both tiers need the same
+ * answer and a disagreement between them is a file that silently stops round-tripping.
+ *
+ * The line is whether more than one renderer must agree on a string, not presentation
+ * against validity — the sentences above are presentation. Admin is the only renderer
+ * today, so a part's label lives there, held against this file by a type. A Portal
+ * collection form, which cannot reach admin's packages, moves the labels here.
+ */
+export declare const FieldTypeSchema: z.ZodEnum<{
+    address: "address";
+    long_text: "long_text";
+    short_text: "short_text";
+}>;
+/**
+ * What the member whose record it is may do with a field.
+ *
+ * A property of a definition rather than of the publisher's namespace, so it has an
+ * answer for any regime that ever stores definitions, not only the publisher's.
+ *
+ * Ordered: `write` includes being able to read. Naming the levels for a publisher is
+ * presentation and stays with whoever renders them.
+ */
+export declare const MEMBER_ACCESS_LEVELS: readonly ['none', 'read', 'write'];
+export type MemberAccess = (typeof MEMBER_ACCESS_LEVELS)[number];
+export declare const MemberAccessSchema: z.ZodEnum<{
+    none: "none";
+    read: "read";
+    write: "write";
+}>;
+export declare const MEMBER_ACCESS: {
+    readonly none: 'none';
+    readonly read: 'read';
+    readonly write: 'write';
+};
+/**
+ * Where a change to a member's values was made, as a member's activity feed names it.
+ * Shared so a place added on the server is one Admin has to be told how to describe.
+ */
+export declare const METAFIELD_CHANGE_SOURCES: readonly ['admin', 'admin_api', 'portal', 'import', 'checkout'];
+export type MetafieldChangeSource = (typeof METAFIELD_CHANGE_SOURCES)[number];
+/** Whether a source is one this build knows how to name; a newer server can send others. */
+export declare const isMetafieldChangeSource: (source: string) => source is MetafieldChangeSource;
+/** A field as an activity feed entry names it: its name is copied so the entry outlives a rename. */
+export declare const MetafieldChangeEventFieldSchema: z.ZodObject<{
+    namespace: z.ZodString;
+    key: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type MetafieldChangeEventField = z.infer<typeof MetafieldChangeEventFieldSchema>;
+/**
+ * An entry on a member's activity feed saying which fields a write changed, as the members
+ * events endpoint returns it. The server builds it and Admin reads it, so both are held to
+ * this one shape. `created_at` is a date on the server and its serialised string in a
+ * client. `source` stays open to places a newer server adds.
+ */
+export interface MetafieldChangeEntry<TDate = string> {
+    id: string;
+    member_id: string;
+    written_by_type: string;
+    written_by_id: string | null;
+    source: MetafieldChangeSource | (string & {});
+    metafields: MetafieldChangeEventField[];
+    created_at: TDate;
+}
+/**
+ * Bytes, not characters, because MySQL TEXT holds 65,535 of them: a character bound would
+ * accept a multibyte value the column cannot hold, and 65,535 emoji is four times over.
+ */
+export declare const MAX_LONG_TEXT_BYTES = 65535;
+/**
+ * The types a composite's parts can declare, each defined once with its rule. A country
+ * code and a postal code both store short text, but they are different things — the
+ * part's type is what a control or a filter dispatches on, the way a field's own type
+ * is for a scalar.
+ */
+export declare const PART_TYPES: {
+    short_text: z.ZodString;
+    postal_code: z.ZodString;
+    country_code: z.ZodString;
+};
+export interface FieldTypeDefinition {
+    /** What kind of value this is, for anything that has to compare one. */
+    kind: import('./structure.js').FieldKind;
+    value: z.ZodType;
+}
+export declare const FIELD_TYPES: {
+    short_text: {
+        kind: "text";
+        value: z.ZodString;
+    };
+    long_text: {
+        kind: "text";
+        value: z.ZodString;
+    };
+    address: {
+        kind: 'record';
+        value: z.ZodObject<{
+            line1: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
+            line2: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
+            city: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
+            state: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
+            postal_code: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
+            country: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
+        }, z.core.$strict>;
+    };
+};
+/** Named for the admin types built on it, which speak of an address rather than a record. */
+export declare const AddressValue: z.ZodObject<{
+    line1: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
+    line2: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
+    city: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
+    state: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
+    postal_code: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
+    country: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
+}, z.core.$strict>;
+export type Address = z.infer<typeof AddressValue>;
+/**
+ * A value of any field type, as a caller holding a field of unknown type must accept it.
+ *
+ * Derived from the schemas rather than listed, so a type added here widens it without
+ * anyone remembering to.
+ */
+export type FieldValue = {
+    [T in FieldType]: z.infer<(typeof FIELD_TYPES)[T]['value']>;
+}[FieldType];
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAA+B,KAAK,SAAS,EAAiB,MAAM,gBAAgB,CAAC;AAI5F,OAAO,EACL,WAAW,EACX,WAAW,EACX,cAAc,EACd,aAAa,EACb,WAAW,EACX,WAAW,EACX,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,QAAQ,GACd,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,eAAO,MAAM,eAAe;;;;EAAyB,CAAC;AAEtD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,YAAI,MAAM,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AACvE,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AACjE,eAAO,MAAM,kBAAkB;;;;EAA+B,CAAC;AAC/D,eAAO,MAAM,aAAa;mBAClB,MAAM;mBACN,MAAM;oBACL,OAAO;CACuC,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,YACnC,OAAO,EACP,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,UAAU,CACF,CAAC;AACX,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,4FAA4F;AAC5F,eAAO,MAAM,uBAAuB,WAAY,MAAM,KAAG,MAAM,IAAI,qBACD,CAAC;AAEnE,qGAAqG;AACrG,eAAO,MAAM,+BAA+B;;;;iBAI1C,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB,CAAC,KAAK,GAAG,MAAM;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,qBAAqB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAC9C,UAAU,EAAE,yBAAyB,EAAE,CAAC;IACxC,UAAU,EAAE,KAAK,CAAC;CACnB;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AA2BzC;;;;;GAKG;AACH,eAAO,MAAM,UAAU;;;;CAwBiB,CAAC;AA+BzC,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,IAAI,EAAE,OAAO,gBAAgB,EAAE,SAAS,CAAC;IACzC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;CAClB;AA2CD,eAAO,MAAM,WAAW;;;;;;;;;;cAHP,QAAQ;;;;;;;;;;CAevB,CAAC;AAEH,6FAA6F;AAC7F,eAAO,MAAM,YAAY;;;;;;;kBAA4B,CAAC;AACtD,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;KAAG,CAAC,IAAI,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;CAAE,CAAC,SAAS,CAAC,CAAC"}

package/build/index.js

@@ -0,0 +1,203 @@
+import { z } from 'zod';
+import { FIELD_PARTS, FIELD_TYPE_IDS } from './structure.js';
+// Re-exported so a caller that needs both halves still has one import. The split is
+// about what a bundle pays for, not about where the catalog lives.
+export { FIELD_KINDS, FIELD_PARTS, FIELD_TYPE_IDS, PART_TYPE_IDS, partTypesOf, subFieldsOf, } from './structure.js';
+/**
+ * The shared catalog of member metafield types.
+ *
+ * ## What a field type is
+ *
+ * A publisher defines fields; a field has a type; a type says what a valid value is. That
+ * last statement lives here and nowhere else, so that Ghost core, which enforces it, and
+ * admin, which gives instant feedback against it, cannot disagree about what is valid.
+ *
+ * A type is one of two things. Most are a value in their own right, declared as the
+ * schema that value must satisfy. An address is a *record*: a set of named parts, each a
+ * value in the same sense, from which the whole type's schema is derived. Nothing stops a
+ * part being a record itself.
+ *
+ * ## What a write may say
+ *
+ * A value is text, and so is every part of one. A write names what it means to change: a
+ * name it does not mention is left as it was, and a name given an empty string is being
+ * cleared. That is why every part accepts empty regardless of its own rule — emptying is
+ * a statement about the write, not about the part.
+ *
+ * A name nobody recognizes is an error rather than a silent drop, at both depths. A
+ * misspelled field key is refused by the values service, which alone knows which fields a
+ * site has defined; a misspelled part is refused here, because a type's parts are declared
+ * in this file and nowhere else. Each is enforced where the names are known.
+ *
+ * ## What a failure says
+ *
+ * A rule carries the sentence shown when it is broken, so the two cannot drift. Each
+ * states what is expected rather than what went wrong, so one sentence covers every way
+ * of breaking that rule.
+ *
+ * The sentences are plain literals with no interpolation, so each is usable as a
+ * translation key. Nothing here translates: Ghost's parser reads `t()` calls out of the
+ * app that renders a string, so that app owns the step. Admin, the only one today, is not
+ * translated at all.
+ *
+ * Two failures keep zod's own wording, both reachable only by a client sending the wrong
+ * JSON shape: a composite handed something that is not an object, and a part nobody
+ * declared. Naming the offending key serves whoever has to fix that client.
+ *
+ * ## What this package will not do
+ *
+ * No presentation beyond that sentence: labels, icons and input controls belong to the
+ * frontend, and so does any wording that depends on where it appears rather than on which
+ * rule was broken. No storage: columns and codecs belong to the backend. One exception
+ * lives in `./csv` — how a value maps onto CSV columns — because both tiers need the same
+ * answer and a disagreement between them is a file that silently stops round-tripping.
+ *
+ * The line is whether more than one renderer must agree on a string, not presentation
+ * against validity — the sentences above are presentation. Admin is the only renderer
+ * today, so a part's label lives there, held against this file by a type. A Portal
+ * collection form, which cannot reach admin's packages, moves the labels here.
+ */
+export const FieldTypeSchema = z.enum(FIELD_TYPE_IDS);
+/**
+ * What the member whose record it is may do with a field.
+ *
+ * A property of a definition rather than of the publisher's namespace, so it has an
+ * answer for any regime that ever stores definitions, not only the publisher's.
+ *
+ * Ordered: `write` includes being able to read. Naming the levels for a publisher is
+ * presentation and stays with whoever renders them.
+ */
+export const MEMBER_ACCESS_LEVELS = ['none', 'read', 'write'];
+export const MemberAccessSchema = z.enum(MEMBER_ACCESS_LEVELS);
+export const MEMBER_ACCESS = {
+    none: 'none',
+    read: 'read',
+    write: 'write',
+};
+/**
+ * Where a change to a member's values was made, as a member's activity feed names it.
+ * Shared so a place added on the server is one Admin has to be told how to describe.
+ */
+export const METAFIELD_CHANGE_SOURCES = [
+    'admin',
+    'admin_api',
+    'portal',
+    'import',
+    'checkout',
+];
+/** Whether a source is one this build knows how to name; a newer server can send others. */
+export const isMetafieldChangeSource = (source) => METAFIELD_CHANGE_SOURCES.includes(source);
+/** A field as an activity feed entry names it: its name is copied so the entry outlives a rename. */
+export const MetafieldChangeEventFieldSchema = z.object({
+    namespace: z.string(),
+    key: z.string(),
+    name: z.string(),
+});
+/**
+ * Bytes, not characters, because MySQL TEXT holds 65,535 of them: a character bound would
+ * accept a multibyte value the column cannot hold, and 65,535 emoji is four times over.
+ */
+export const MAX_LONG_TEXT_BYTES = 65535;
+// TextEncoder rather than Buffer: this package runs in the browser too.
+const byteLength = (value) => new TextEncoder().encode(value).length;
+/**
+ * Every value and every part is built from this, so no two types can disagree about
+ * whitespace: a value of nothing but spaces is nothing, whichever field it was typed
+ * into. Trimming first also makes each bound measure the value rather than its padding.
+ *
+ * Builders are named after what a value is rather than taking a size, so that a bound
+ * lives with everything else true of that thing instead of as a number at the call site.
+ */
+const text = () => z.string({ error: 'Enter text.' }).trim();
+const longText = () => text().refine((value) => byteLength(value) <= MAX_LONG_TEXT_BYTES, {
+    error: 'This text is too long to save. Shorten it a little.',
+});
+/**
+ * The types a composite's parts can declare, each defined once with its rule. A country
+ * code and a postal code both store short text, but they are different things — the
+ * part's type is what a control or a filter dispatches on, the way a field's own type
+ * is for a scalar.
+ */
+export const PART_TYPES = {
+    short_text: text().max(255, { error: 'Use 255 characters or fewer.' }),
+    // A postal code, bounded well under a street address because no country's is long. The
+    // bound is a sanity limit rather than a format: postal codes vary too much between
+    // countries to check the shape of one without knowing which country it is for, and the
+    // country is a sibling part rather than something this can see.
+    postal_code: text().max(32, { error: 'Use 32 characters or fewer.' }),
+    // The shape of an ISO 3166-1 alpha-2 code, deliberately not checked against the list of
+    // them. Membership of that list is contested, and a closed list here would make Ghost
+    // the arbiter of it for every member of every site. The collection form can offer
+    // countries to pick from without this deciding which ones exist.
+    //
+    // Case is normalized so that `gb` and `GB` are not two values for one place, which a
+    // filter for either would silently half-miss.
+    //
+    // Checked as two ASCII letters on the way in rather than by length on the way out,
+    // because uppercasing does not preserve length: `ß` becomes `SS` and `aß` becomes `ASS`.
+    country_code: text()
+        .regex(/^[A-Za-z]{2}$/, { error: 'Enter a 2-letter country code, like US.' })
+        .toUpperCase(),
+    // Every part type declared next door needs a rule here, and nothing here may
+    // invent one that is not declared there.
+};
+const partSchemas = PART_TYPES;
+/**
+ * A part as a write may name it: absent, empty, or a value of its own kind.
+ *
+ * A rule that is a bound would admit empty on its own; one that is a format would not,
+ * and would leave its part the only one that could be set but never removed.
+ */
+const clearable = (schema) => text()
+    .pipe(z.union([z.literal(''), schema]))
+    .optional();
+/**
+ * Every type states its kind alongside its schema, so no type can exist that nothing knows
+ * how to compare. The `Record<FieldType, …>` is what makes that exhaustive: an id added to
+ * `FIELD_TYPE_IDS` fails to compile until it is declared here.
+ */
+function defineFieldTypes(declarations) {
+    return declarations;
+}
+/**
+ * Every part is optional, because none of an address's exists everywhere: there is no
+ * postal code in Ireland or Hong Kong, and no city in an Irish townland address. Which
+ * parts a value needs is a per-country question, and only the collection form knows the
+ * country. What holds instead is that a value must name at least one part.
+ *
+ * The type check below is load-bearing rather than defensive. An optional part that is
+ * explicitly undefined survives parsing as a key holding undefined, and a bare presence
+ * check would let `{line1: undefined}` through as if it named something.
+ */
+function record(type, { error }) {
+    // The parts, and what each holds, are declared in `./structure`; this turns each
+    // into the rule a write must satisfy. Reading them from there is what stops the
+    // structure a renderer draws and the rules a server enforces from drifting apart.
+    const declared = FIELD_PARTS[type];
+    // Restated for the type system, which loses the key-to-part mapping through
+    // `Object.fromEntries`. Without it the parsed value widens to a string-keyed record,
+    // and a caller could name a part that compiles and is then refused at runtime.
+    const shape = Object.fromEntries(Object.entries(declared).map(([key, partType]) => [key, clearable(partSchemas[partType])]));
+    // Strict, so a part nobody declared is refused rather than dropped. That refusal keeps
+    // zod's wording, which names the offending key.
+    const value = z
+        .strictObject(shape)
+        .refine((parts) => Object.values(parts).some((entry) => typeof entry === 'string'), { error });
+    return { kind: 'record', value };
+}
+export const FIELD_TYPES = defineFieldTypes({
+    short_text: { kind: 'text', value: PART_TYPES.short_text },
+    long_text: { kind: 'text', value: longText() },
+    // An address is a delivery address, so its bounds are what a courier will accept
+    // rather than what the column could hold. Modeled on Stripe's Address object.
+    //
+    // Who the parcel is addressed to is not here. A parcel needs a name as well as an
+    // address, but that is a fact about posting parcels rather than about either type,
+    // and the name is often not the account name — gift subscriptions, workplace
+    // deliveries, c/o. A site that needs one keeps it in a field of its own, which is
+    // also how Stripe hands it back: beside the address rather than inside it.
+    address: record('address', { error: 'Enter at least one part of the address.' }),
+});
+/** Named for the admin types built on it, which speak of an address rather than a record. */
+export const AddressValue = FIELD_TYPES.address.value;
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/build/structure.d.ts

@@ -0,0 +1,78 @@
+/**
+ * What a field type is made of, with no opinion on what a valid value looks like.
+ *
+ * This is the half of the catalog a renderer needs. Drawing an address means knowing
+ * it has six parts, in that order, and that the last of them holds a country code —
+ * nothing about lengths, formats, or what happens when one is left blank.
+ *
+ * It is separate from `./index` because that half is built out of zod, and zod is
+ * sixty-odd kilobytes. Ghost's server enforces the rules and can afford them; Portal
+ * only draws the inputs, and it loads on every page view of every themed site. Split
+ * this way a renderer imports well under a kilobyte and still gets the types.
+ *
+ * The two halves cannot drift, because the schemas are built from these declarations
+ * rather than beside them: adding a part here without a rule in `./index` fails to
+ * compile.
+ */
+/** The source for the union type, the zod enum and the `FIELD_TYPES` keys alike. */
+export declare const FIELD_TYPE_IDS: readonly ['short_text', 'long_text', 'address'];
+export type FieldType = (typeof FIELD_TYPE_IDS)[number];
+/**
+ * What kind of thing a type's value is, as anything comparing values needs to know.
+ *
+ * Coarser than the type: `short_text` and `long_text` are both text, and differ only in
+ * how much of it. This is the level at which a value can be ordered, matched or grouped,
+ * so it is what a filter, a sort or an export reads to decide how to treat a value —
+ * without either of them enumerating the types themselves.
+ *
+ * Deliberately not presentation: it says a value is a date, not that its operator is
+ * called "is before". Naming the operators stays with whoever renders them.
+ */
+export declare const FIELD_KINDS: readonly ['text', 'date', 'number', 'record'];
+export type FieldKind = (typeof FIELD_KINDS)[number];
+/**
+ * The types a composite's parts can declare. A country code and a postal code both
+ * store short text, but they are different things — the part's type is what a control
+ * or a filter dispatches on, the way a field's own type is for a scalar.
+ */
+export declare const PART_TYPE_IDS: readonly ['short_text', 'postal_code', 'country_code'];
+export type PartType = (typeof PART_TYPE_IDS)[number];
+/**
+ * Which parts each type has, in the order they are shown, and what each part holds.
+ * `null` for a type whose value is a single thing.
+ *
+ * An address is a delivery address, modeled on Stripe's Address object. Who the parcel
+ * is addressed to is not here: a parcel needs a name as well as an address, but that is
+ * a fact about posting parcels rather than about either type, and the name is often not
+ * the account name — gift subscriptions, workplace deliveries, c/o. A site that needs
+ * one keeps it in a field of its own, which is also how Stripe hands it back.
+ */
+export declare const FIELD_PARTS: {
+    readonly short_text: null;
+    readonly long_text: null;
+    readonly address: {
+        readonly line1: 'short_text';
+        readonly line2: 'short_text';
+        readonly city: 'short_text';
+        readonly state: 'short_text';
+        readonly postal_code: 'postal_code';
+        readonly country: 'country_code';
+    };
+};
+/**
+ * The parts a record type declares, or never for a type whose value is a single thing.
+ *
+ * Distributed over `T`, so a caller holding a type it only knows as `FieldType` gets
+ * every part any type declares rather than the empty intersection of all of them.
+ */
+export type PartsOf<T extends FieldType> = T extends FieldType ? (typeof FIELD_PARTS)[T] extends null ? never : Extract<keyof (typeof FIELD_PARTS)[T], string> : never;
+/**
+ * The parts of a record type in declaration order, or null for a type with none.
+ *
+ * Typed to the parts the caller's type declares, so a caller holding one of these can
+ * index a value of that type without restating which parts exist.
+ */
+export declare function subFieldsOf<T extends FieldType>(type: T): PartsOf<T>[] | null;
+/** Each part's declared type, keyed by part; null for a type with none, and for one this build has never heard of. */
+export declare function partTypesOf<T extends FieldType>(type: T): Record<PartsOf<T>, PartType> | null;
+//# sourceMappingURL=structure.d.ts.map

package/build/structure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure.d.ts","sourceRoot":"","sources":["../src/structure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,oFAAoF;AACpF,eAAO,MAAM,cAAc,YAAI,YAAY,EAAE,WAAW,EAAE,SAAS,CAAU,CAAC;AAC9E,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,YAAI,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AACzE,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,aAAa,YAAI,YAAY,EAAE,aAAa,EAAE,cAAc,CAAU,CAAC;AACpF,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW;;;;iBAIpB,KAAK,EAAE,YAAY;iBACnB,KAAK,EAAE,YAAY;iBACnB,IAAI,EAAE,YAAY;iBAClB,KAAK,EAAE,YAAY;iBACnB,WAAW,EAAE,aAAa;iBAC1B,OAAO,EAAE,cAAc;;CAEsD,CAAC;AAElF;;;;;GAKG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,SAAS,IAAI,CAAC,SAAS,SAAS,GAC1D,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,GAClC,KAAK,GACL,OAAO,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,GAChD,KAAK,CAAC;AAEV;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAK7E;AAED,sHAAsH;AACtH,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,IAAI,CAG7F"}

package/build/structure.js

@@ -0,0 +1,76 @@
+/**
+ * What a field type is made of, with no opinion on what a valid value looks like.
+ *
+ * This is the half of the catalog a renderer needs. Drawing an address means knowing
+ * it has six parts, in that order, and that the last of them holds a country code —
+ * nothing about lengths, formats, or what happens when one is left blank.
+ *
+ * It is separate from `./index` because that half is built out of zod, and zod is
+ * sixty-odd kilobytes. Ghost's server enforces the rules and can afford them; Portal
+ * only draws the inputs, and it loads on every page view of every themed site. Split
+ * this way a renderer imports well under a kilobyte and still gets the types.
+ *
+ * The two halves cannot drift, because the schemas are built from these declarations
+ * rather than beside them: adding a part here without a rule in `./index` fails to
+ * compile.
+ */
+/** The source for the union type, the zod enum and the `FIELD_TYPES` keys alike. */
+export const FIELD_TYPE_IDS = ['short_text', 'long_text', 'address'];
+/**
+ * What kind of thing a type's value is, as anything comparing values needs to know.
+ *
+ * Coarser than the type: `short_text` and `long_text` are both text, and differ only in
+ * how much of it. This is the level at which a value can be ordered, matched or grouped,
+ * so it is what a filter, a sort or an export reads to decide how to treat a value —
+ * without either of them enumerating the types themselves.
+ *
+ * Deliberately not presentation: it says a value is a date, not that its operator is
+ * called "is before". Naming the operators stays with whoever renders them.
+ */
+export const FIELD_KINDS = ['text', 'date', 'number', 'record'];
+/**
+ * The types a composite's parts can declare. A country code and a postal code both
+ * store short text, but they are different things — the part's type is what a control
+ * or a filter dispatches on, the way a field's own type is for a scalar.
+ */
+export const PART_TYPE_IDS = ['short_text', 'postal_code', 'country_code'];
+/**
+ * Which parts each type has, in the order they are shown, and what each part holds.
+ * `null` for a type whose value is a single thing.
+ *
+ * An address is a delivery address, modeled on Stripe's Address object. Who the parcel
+ * is addressed to is not here: a parcel needs a name as well as an address, but that is
+ * a fact about posting parcels rather than about either type, and the name is often not
+ * the account name — gift subscriptions, workplace deliveries, c/o. A site that needs
+ * one keeps it in a field of its own, which is also how Stripe hands it back.
+ */
+export const FIELD_PARTS = {
+    short_text: null,
+    long_text: null,
+    address: {
+        line1: 'short_text',
+        line2: 'short_text',
+        city: 'short_text',
+        state: 'short_text',
+        postal_code: 'postal_code',
+        country: 'country_code',
+    },
+};
+/**
+ * The parts of a record type in declaration order, or null for a type with none.
+ *
+ * Typed to the parts the caller's type declares, so a caller holding one of these can
+ * index a value of that type without restating which parts exist.
+ */
+export function subFieldsOf(type) {
+    // Optional because a caller built against an older catalog than the server it talks
+    // to reaches here with a type this build has never heard of, which reads as no parts.
+    const parts = FIELD_PARTS[type];
+    return parts ? Object.keys(parts) : null;
+}
+/** Each part's declared type, keyed by part; null for a type with none, and for one this build has never heard of. */
+export function partTypesOf(type) {
+    const parts = FIELD_PARTS[type];
+    return parts ? { ...parts } : null;
+}
+//# sourceMappingURL=structure.js.map

package/build/structure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure.js","sourceRoot":"","sources":["../src/structure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,oFAAoF;AACpF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,YAAY,EAAE,WAAW,EAAE,SAAS,CAAU,CAAC;AAG9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAGzE;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,YAAY,EAAE,aAAa,EAAE,cAAc,CAAU,CAAC;AAGpF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,UAAU,EAAE,IAAI;IAChB,SAAS,EAAE,IAAI;IACf,OAAO,EAAE;QACP,KAAK,EAAE,YAAY;QACnB,KAAK,EAAE,YAAY;QACnB,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,YAAY;QACnB,WAAW,EAAE,aAAa;QAC1B,OAAO,EAAE,cAAc;KACxB;CAC8E,CAAC;AAclF;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAsB,IAAO;IACtD,oFAAoF;IACpF,sFAAsF;IACtF,MAAM,KAAK,GAA0D,WAAW,CAAC,IAAI,CAAC,CAAC;IACvF,OAAO,KAAK,CAAC,CAAC,CAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAkB,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7D,CAAC;AAED,sHAAsH;AACtH,MAAM,UAAU,WAAW,CAAsB,IAAO;IACtD,MAAM,KAAK,GAA0D,WAAW,CAAC,IAAI,CAAC,CAAC;IACvF,OAAO,KAAK,CAAC,CAAC,CAAE,EAAE,GAAG,KAAK,EAAmC,CAAC,CAAC,CAAC,IAAI,CAAC;AACvE,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@tryghost/metafield-types",
+  "version": "0.1.0",
+  "description": "Ghost member custom field types: which types exist, what each is made of, and how a value of each is validated",
+  "license": "MIT",
+  "author": "Ghost Foundation",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TryGhost/Ghost.git",
+    "directory": "packages/metafield-types"
+  },
+  "files": [
+    "build"
+  ],
+  "type": "module",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    },
+    "./structure": {
+      "types": "./build/structure.d.ts",
+      "default": "./build/structure.js"
+    },
+    "./identity": {
+      "types": "./build/identity.d.ts",
+      "default": "./build/identity.js"
+    },
+    "./countries": {
+      "types": "./build/countries.d.ts",
+      "default": "./build/countries.js"
+    }
+  },
+  "dependencies": {
+    "zod": "4.4.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test:unit": "NODE_ENV=testing vitest run --coverage",
+    "test": "pnpm run '/^test:/'",
+    "test:types": "tsc --noEmit -p test/tsconfig.json",
+    "lint:code": "eslint src/ --cache",
+    "lint:test": "eslint test/ --cache",
+    "lint": "pnpm run '/^lint:/'"
+  }
+}