@parrel/ledger 0.0.0-stage → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (239) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +793 -2
  3. package/dist/cli/commands.d.ts +51 -0
  4. package/dist/cli/commands.d.ts.map +1 -0
  5. package/dist/cli/commands.js +968 -0
  6. package/dist/cli/commands.js.map +1 -0
  7. package/dist/cli/index.d.ts +24 -0
  8. package/dist/cli/index.d.ts.map +1 -0
  9. package/dist/cli/index.js +35 -0
  10. package/dist/cli/index.js.map +1 -0
  11. package/dist/cli/parrel.d.ts +3 -0
  12. package/dist/cli/parrel.d.ts.map +1 -0
  13. package/dist/cli/parrel.js +5 -0
  14. package/dist/cli/parrel.js.map +1 -0
  15. package/dist/cli/utils/angular-setup.d.ts +14 -0
  16. package/dist/cli/utils/angular-setup.d.ts.map +1 -0
  17. package/dist/cli/utils/angular-setup.js +96 -0
  18. package/dist/cli/utils/angular-setup.js.map +1 -0
  19. package/dist/cli/utils/api-tree-builder.d.ts +24 -0
  20. package/dist/cli/utils/api-tree-builder.d.ts.map +1 -0
  21. package/dist/cli/utils/api-tree-builder.js +146 -0
  22. package/dist/cli/utils/api-tree-builder.js.map +1 -0
  23. package/dist/cli/utils/bundle-reader.d.ts +185 -0
  24. package/dist/cli/utils/bundle-reader.d.ts.map +1 -0
  25. package/dist/cli/utils/bundle-reader.js +518 -0
  26. package/dist/cli/utils/bundle-reader.js.map +1 -0
  27. package/dist/cli/utils/collision-detector.d.ts +21 -0
  28. package/dist/cli/utils/collision-detector.d.ts.map +1 -0
  29. package/dist/cli/utils/collision-detector.js +53 -0
  30. package/dist/cli/utils/collision-detector.js.map +1 -0
  31. package/dist/cli/utils/map-fields.d.ts +42 -0
  32. package/dist/cli/utils/map-fields.d.ts.map +1 -0
  33. package/dist/cli/utils/map-fields.js +90 -0
  34. package/dist/cli/utils/map-fields.js.map +1 -0
  35. package/dist/cli/utils/map-validator.d.ts +42 -0
  36. package/dist/cli/utils/map-validator.d.ts.map +1 -0
  37. package/dist/cli/utils/map-validator.js +119 -0
  38. package/dist/cli/utils/map-validator.js.map +1 -0
  39. package/dist/cli/utils/media-file.d.ts +41 -0
  40. package/dist/cli/utils/media-file.d.ts.map +1 -0
  41. package/dist/cli/utils/media-file.js +72 -0
  42. package/dist/cli/utils/media-file.js.map +1 -0
  43. package/dist/cli/utils/media-validator.d.ts +10 -0
  44. package/dist/cli/utils/media-validator.d.ts.map +1 -0
  45. package/dist/cli/utils/media-validator.js +85 -0
  46. package/dist/cli/utils/media-validator.js.map +1 -0
  47. package/dist/cli/utils/mock-augmenter.d.ts +19 -0
  48. package/dist/cli/utils/mock-augmenter.d.ts.map +1 -0
  49. package/dist/cli/utils/mock-augmenter.js +102 -0
  50. package/dist/cli/utils/mock-augmenter.js.map +1 -0
  51. package/dist/cli/utils/mock-validator.d.ts +27 -0
  52. package/dist/cli/utils/mock-validator.d.ts.map +1 -0
  53. package/dist/cli/utils/mock-validator.js +214 -0
  54. package/dist/cli/utils/mock-validator.js.map +1 -0
  55. package/dist/cli/utils/project-dir.d.ts +24 -0
  56. package/dist/cli/utils/project-dir.d.ts.map +1 -0
  57. package/dist/cli/utils/project-dir.js +32 -0
  58. package/dist/cli/utils/project-dir.js.map +1 -0
  59. package/dist/cli/utils/schema-loader.d.ts +19 -0
  60. package/dist/cli/utils/schema-loader.d.ts.map +1 -0
  61. package/dist/cli/utils/schema-loader.js +101 -0
  62. package/dist/cli/utils/schema-loader.js.map +1 -0
  63. package/dist/cli/utils/server-entry.d.ts +34 -0
  64. package/dist/cli/utils/server-entry.d.ts.map +1 -0
  65. package/dist/cli/utils/server-entry.js +111 -0
  66. package/dist/cli/utils/server-entry.js.map +1 -0
  67. package/dist/cli/utils/sync.d.ts +116 -0
  68. package/dist/cli/utils/sync.d.ts.map +1 -0
  69. package/dist/cli/utils/sync.js +134 -0
  70. package/dist/cli/utils/sync.js.map +1 -0
  71. package/dist/client/index.d.ts +39 -0
  72. package/dist/client/index.d.ts.map +1 -0
  73. package/dist/client/index.js +88 -0
  74. package/dist/client/index.js.map +1 -0
  75. package/dist/core/browser-session.d.ts +5 -0
  76. package/dist/core/browser-session.d.ts.map +1 -0
  77. package/dist/core/browser-session.js +12 -0
  78. package/dist/core/browser-session.js.map +1 -0
  79. package/dist/core/cache.d.ts +80 -0
  80. package/dist/core/cache.d.ts.map +1 -0
  81. package/dist/core/cache.js +95 -0
  82. package/dist/core/cache.js.map +1 -0
  83. package/dist/core/client.d.ts +64 -0
  84. package/dist/core/client.d.ts.map +1 -0
  85. package/dist/core/client.js +281 -0
  86. package/dist/core/client.js.map +1 -0
  87. package/dist/core/config.d.ts +20 -0
  88. package/dist/core/config.d.ts.map +1 -0
  89. package/dist/core/config.js +32 -0
  90. package/dist/core/config.js.map +1 -0
  91. package/dist/core/copy-read.d.ts +25 -0
  92. package/dist/core/copy-read.d.ts.map +1 -0
  93. package/dist/core/copy-read.js +123 -0
  94. package/dist/core/copy-read.js.map +1 -0
  95. package/dist/core/define-ledger.d.ts +38 -0
  96. package/dist/core/define-ledger.d.ts.map +1 -0
  97. package/dist/core/define-ledger.js +65 -0
  98. package/dist/core/define-ledger.js.map +1 -0
  99. package/dist/core/deprecated.d.ts +16 -0
  100. package/dist/core/deprecated.d.ts.map +1 -0
  101. package/dist/core/deprecated.js +14 -0
  102. package/dist/core/deprecated.js.map +1 -0
  103. package/dist/core/env.d.ts +103 -0
  104. package/dist/core/env.d.ts.map +1 -0
  105. package/dist/core/env.js +208 -0
  106. package/dist/core/env.js.map +1 -0
  107. package/dist/core/error-codes.generated.d.ts +12 -0
  108. package/dist/core/error-codes.generated.d.ts.map +1 -0
  109. package/dist/core/error-codes.generated.js +3 -0
  110. package/dist/core/error-codes.generated.js.map +1 -0
  111. package/dist/core/get-content.d.ts +62 -0
  112. package/dist/core/get-content.d.ts.map +1 -0
  113. package/dist/core/get-content.js +86 -0
  114. package/dist/core/get-content.js.map +1 -0
  115. package/dist/core/get-media.d.ts +58 -0
  116. package/dist/core/get-media.d.ts.map +1 -0
  117. package/dist/core/get-media.js +89 -0
  118. package/dist/core/get-media.js.map +1 -0
  119. package/dist/core/manifest.d.ts +38 -0
  120. package/dist/core/manifest.d.ts.map +1 -0
  121. package/dist/core/manifest.js +93 -0
  122. package/dist/core/manifest.js.map +1 -0
  123. package/dist/core/media-proxy.d.ts +41 -0
  124. package/dist/core/media-proxy.d.ts.map +1 -0
  125. package/dist/core/media-proxy.js +219 -0
  126. package/dist/core/media-proxy.js.map +1 -0
  127. package/dist/core/package-info.d.ts +34 -0
  128. package/dist/core/package-info.d.ts.map +1 -0
  129. package/dist/core/package-info.js +39 -0
  130. package/dist/core/package-info.js.map +1 -0
  131. package/dist/core/parrel-error.d.ts +160 -0
  132. package/dist/core/parrel-error.d.ts.map +1 -0
  133. package/dist/core/parrel-error.js +198 -0
  134. package/dist/core/parrel-error.js.map +1 -0
  135. package/dist/core/transform-content.d.ts +42 -0
  136. package/dist/core/transform-content.d.ts.map +1 -0
  137. package/dist/core/transform-content.js +185 -0
  138. package/dist/core/transform-content.js.map +1 -0
  139. package/dist/core/types.d.ts +406 -0
  140. package/dist/core/types.d.ts.map +1 -0
  141. package/dist/core/types.js +11 -0
  142. package/dist/core/types.js.map +1 -0
  143. package/dist/errors/error-messages.generated.d.ts +5 -0
  144. package/dist/errors/error-messages.generated.d.ts.map +1 -0
  145. package/dist/errors/error-messages.generated.js +971 -0
  146. package/dist/errors/error-messages.generated.js.map +1 -0
  147. package/dist/errors/get-error-info.d.ts +29 -0
  148. package/dist/errors/get-error-info.d.ts.map +1 -0
  149. package/dist/errors/get-error-info.js +43 -0
  150. package/dist/errors/get-error-info.js.map +1 -0
  151. package/dist/errors/index.d.ts +4 -0
  152. package/dist/errors/index.d.ts.map +1 -0
  153. package/dist/errors/index.js +4 -0
  154. package/dist/errors/index.js.map +1 -0
  155. package/dist/errors/types.d.ts +19 -0
  156. package/dist/errors/types.d.ts.map +1 -0
  157. package/dist/errors/types.js +2 -0
  158. package/dist/errors/types.js.map +1 -0
  159. package/dist/generated.d.ts +29 -0
  160. package/dist/generated.d.ts.map +1 -0
  161. package/dist/generated.js +29 -0
  162. package/dist/generated.js.map +1 -0
  163. package/dist/index.d.ts +19 -0
  164. package/dist/index.d.ts.map +1 -0
  165. package/dist/index.js +16 -0
  166. package/dist/index.js.map +1 -0
  167. package/dist/mock/dev-media.d.ts +15 -0
  168. package/dist/mock/dev-media.d.ts.map +1 -0
  169. package/dist/mock/dev-media.js +52 -0
  170. package/dist/mock/dev-media.js.map +1 -0
  171. package/dist/mock/file-store.d.ts +44 -0
  172. package/dist/mock/file-store.d.ts.map +1 -0
  173. package/dist/mock/file-store.js +170 -0
  174. package/dist/mock/file-store.js.map +1 -0
  175. package/dist/mock/index.d.ts +4 -0
  176. package/dist/mock/index.d.ts.map +1 -0
  177. package/dist/mock/index.js +3 -0
  178. package/dist/mock/index.js.map +1 -0
  179. package/dist/mock/media-fields.d.ts +25 -0
  180. package/dist/mock/media-fields.d.ts.map +1 -0
  181. package/dist/mock/media-fields.js +54 -0
  182. package/dist/mock/media-fields.js.map +1 -0
  183. package/dist/mock/mock-adapter.d.ts +65 -0
  184. package/dist/mock/mock-adapter.d.ts.map +1 -0
  185. package/dist/mock/mock-adapter.js +431 -0
  186. package/dist/mock/mock-adapter.js.map +1 -0
  187. package/dist/mock/mock-errors.d.ts +18 -0
  188. package/dist/mock/mock-errors.d.ts.map +1 -0
  189. package/dist/mock/mock-errors.js +56 -0
  190. package/dist/mock/mock-errors.js.map +1 -0
  191. package/dist/mock/node-import.d.ts +13 -0
  192. package/dist/mock/node-import.d.ts.map +1 -0
  193. package/dist/mock/node-import.js +16 -0
  194. package/dist/mock/node-import.js.map +1 -0
  195. package/dist/mock/seed-mock-store.d.ts +14 -0
  196. package/dist/mock/seed-mock-store.d.ts.map +1 -0
  197. package/dist/mock/seed-mock-store.js +106 -0
  198. package/dist/mock/seed-mock-store.js.map +1 -0
  199. package/dist/mock/shared-memory-store.d.ts +35 -0
  200. package/dist/mock/shared-memory-store.d.ts.map +1 -0
  201. package/dist/mock/shared-memory-store.js +46 -0
  202. package/dist/mock/shared-memory-store.js.map +1 -0
  203. package/dist/next/dev-rendering-helpers.d.ts +78 -0
  204. package/dist/next/dev-rendering-helpers.d.ts.map +1 -0
  205. package/dist/next/dev-rendering-helpers.js +103 -0
  206. package/dist/next/dev-rendering-helpers.js.map +1 -0
  207. package/dist/next/index.d.ts +35 -0
  208. package/dist/next/index.d.ts.map +1 -0
  209. package/dist/next/index.js +33 -0
  210. package/dist/next/index.js.map +1 -0
  211. package/dist/next/next-cache-adapter.d.ts +11 -0
  212. package/dist/next/next-cache-adapter.d.ts.map +1 -0
  213. package/dist/next/next-cache-adapter.js +12 -0
  214. package/dist/next/next-cache-adapter.js.map +1 -0
  215. package/dist/nuxt/index.d.ts +22 -0
  216. package/dist/nuxt/index.d.ts.map +1 -0
  217. package/dist/nuxt/index.js +57 -0
  218. package/dist/nuxt/index.js.map +1 -0
  219. package/dist/sveltekit/index.d.ts +35 -0
  220. package/dist/sveltekit/index.d.ts.map +1 -0
  221. package/dist/sveltekit/index.js +56 -0
  222. package/dist/sveltekit/index.js.map +1 -0
  223. package/dist/ui/content-editor.d.ts +9 -0
  224. package/dist/ui/content-editor.d.ts.map +1 -0
  225. package/dist/ui/content-editor.js +27 -0
  226. package/dist/ui/content-editor.js.map +1 -0
  227. package/dist/ui/index.d.ts +8 -0
  228. package/dist/ui/index.d.ts.map +1 -0
  229. package/dist/ui/index.js +8 -0
  230. package/dist/ui/index.js.map +1 -0
  231. package/dist/ui/ledger-overlay.d.ts +10 -0
  232. package/dist/ui/ledger-overlay.d.ts.map +1 -0
  233. package/dist/ui/ledger-overlay.js +27 -0
  234. package/dist/ui/ledger-overlay.js.map +1 -0
  235. package/dist/ui/media-uploader.d.ts +9 -0
  236. package/dist/ui/media-uploader.d.ts.map +1 -0
  237. package/dist/ui/media-uploader.js +27 -0
  238. package/dist/ui/media-uploader.js.map +1 -0
  239. package/package.json +134 -6
@@ -0,0 +1,406 @@
1
+ import type { ParrelMode } from "./env.js";
2
+ /**
3
+ * Ledger content path format:
4
+ * - Simple: "home.header"
5
+ * - Array access: "home.items[0]", "home.items[last]", "home.items[0..2]"
6
+ */
7
+ export type LedgerContentPath = string;
8
+ export type LedgerMediaPath = string;
9
+ export interface ManifestEntryDto {
10
+ name: string;
11
+ hash: string;
12
+ schema?: string;
13
+ size?: number;
14
+ type?: string;
15
+ }
16
+ export interface ManifestDto {
17
+ version: number;
18
+ updatedAt: string;
19
+ resources?: ManifestEntryDto[];
20
+ media?: ManifestEntryDto[];
21
+ maps?: ManifestEntryDto[];
22
+ }
23
+ /**
24
+ * Media field value: object with file reference and alt text
25
+ */
26
+ export interface MediaFieldValue {
27
+ file: string;
28
+ alt: string;
29
+ }
30
+ /**
31
+ * The field types of a Ledger map (rulebook LED-3): exactly these seven. A map with any other type is refused.
32
+ * `media-reference` is handled like `media`: the same JSON value, the same checks and the same generated type.
33
+ */
34
+ export type LedgerFieldType = "string" | "number" | "boolean" | "media" | "media-reference" | "array" | "object";
35
+ /** The seven field types of {@link LedgerFieldType}, for code that checks a map. */
36
+ export declare const LEDGER_FIELD_TYPES: readonly LedgerFieldType[];
37
+ /**
38
+ * Field definition in a Ledger schema
39
+ */
40
+ export interface LedgerFieldDefinition {
41
+ type: LedgerFieldType;
42
+ fields?: Record<string, LedgerFieldDefinition>;
43
+ items?: LedgerFieldDefinition;
44
+ mediaType?: string;
45
+ }
46
+ /**
47
+ * The fields of a map. The filename is the resource name.
48
+ *
49
+ * A map file is either flat (every top-level key is a field, except the settings `mediaDir`, `version` and `name`)
50
+ * or a wrapper `{ "mediaDir": "...", "fields": { ... } }`, as the Ledger service accepts. The CLI reads the fields of a
51
+ * map file with `getMapFields` and passes only the fields on, so this type holds fields and no settings.
52
+ */
53
+ export type LedgerMapSchema = Record<string, LedgerFieldDefinition>;
54
+ /**
55
+ * Mock adapter data (flat structure)
56
+ * Example: { homepage: { title: "...", items: [...] }, product: { ... } }
57
+ */
58
+ export type MockAdapterData = Record<string, unknown>;
59
+ /**
60
+ * Media field descriptor - metadata about which fields in a resource are media fields
61
+ */
62
+ export interface MediaFieldDescriptor {
63
+ mediaType: string;
64
+ rawFieldName: string;
65
+ }
66
+ /**
67
+ * Media field descriptors for a resource - maps field name to descriptor
68
+ */
69
+ export type MediaFieldDescriptors = Record<string, MediaFieldDescriptor>;
70
+ export interface LedgerGetContentInput {
71
+ path: LedgerContentPath;
72
+ checkOnly?: boolean;
73
+ }
74
+ export interface LedgerGetMediaInput {
75
+ path: LedgerMediaPath;
76
+ checkOnly?: boolean;
77
+ }
78
+ export interface LedgerUploadContentInput {
79
+ path: LedgerContentPath;
80
+ value: unknown;
81
+ }
82
+ export interface LedgerUploadMediaInput {
83
+ path: LedgerMediaPath;
84
+ file: File;
85
+ }
86
+ /**
87
+ * Adapter interface for Ledger operations.
88
+ * Implementations can be HTTP-based, mock-based, or any other backend.
89
+ */
90
+ export interface ParrelLedgerAdapter {
91
+ /**
92
+ * Optional marker for mock adapters.
93
+ * Internal use: allows relaxed auth checks in local mock development.
94
+ */
95
+ isMockAdapter?: boolean;
96
+ /**
97
+ * Retrieve content by path
98
+ */
99
+ getContent?(path: LedgerContentPath, options?: ContentAccessOptions): Promise<unknown>;
100
+ /**
101
+ * Retrieve media by path (always returns URL string)
102
+ */
103
+ getMedia?(path: LedgerMediaPath, options?: ContentAccessOptions): Promise<string>;
104
+ /**
105
+ * Upload or update content (requires auth).
106
+ * Returns void on success. Throws on failure.
107
+ */
108
+ uploadContent?(path: LedgerContentPath, value: unknown): Promise<void>;
109
+ /**
110
+ * Upload or update media (requires auth).
111
+ * Returns void on success. Throws on failure.
112
+ */
113
+ uploadMedia?(path: LedgerMediaPath, file: File): Promise<void>;
114
+ /**
115
+ * Get the current manifest (resource/media list with hashes)
116
+ */
117
+ getManifest?(): Promise<ManifestDto>;
118
+ }
119
+ /**
120
+ * Configuration for the Parrel Ledger system
121
+ */
122
+ export interface DefineParrelLedgerConfig {
123
+ /**
124
+ * Service instance slug (e.g., "my-site")
125
+ */
126
+ slug: string;
127
+ /**
128
+ * Optional path to the file-based mock store used outside production.
129
+ * Defaults to "node_modules/.cache/parrel".
130
+ */
131
+ mockDataDir?: string;
132
+ /**
133
+ * The mock content for an app that runs only in a browser (React, Vue, Angular), where the mock cannot read
134
+ * `parrel/ledger/mock.json` itself. Import the file and pass it, as `npx parrel ledger init` writes it:
135
+ * `import mockData from "../parrel/ledger/mock.json"`. Used outside production, when `mode` is not `"live"`.
136
+ * The mock keeps it in memory, with the same rules and error codes as the file mock; changes are lost when the page
137
+ * reloads. Without it, the first call in a browser throws `SD06000007`. On a server the content is read from
138
+ * `parrel/ledger/mock.json` and this value is merged into it.
139
+ *
140
+ * @example
141
+ * ```ts
142
+ * import mockData from "../parrel/ledger/mock.json";
143
+ * defineParrelLedger({ slug: "your-service-slug", mockData });
144
+ * ```
145
+ */
146
+ mockData?: MockAdapterData;
147
+ /**
148
+ * In a browser, the URL path below which the mock `getMedia()` expects the media files, for example
149
+ * `/parrel/ledger` gives `/parrel/ledger/hero.svg`. Put the files in the `public/parrel/ledger/` folder of the
150
+ * app (Vite serves `public/` from the root). A file that is uploaded in the page is returned as a data URL.
151
+ * Defaults to `/parrel/ledger`. On a server the dev media route is used instead.
152
+ */
153
+ mockMediaPath?: string;
154
+ /**
155
+ * Optional cache configuration
156
+ */
157
+ cache?: {
158
+ /** Set to `false` to turn the cache off: every call asks the service. Defaults to `true`. */
159
+ enabled?: boolean;
160
+ /**
161
+ * How long, in seconds, a copy of a resource or a media URL is fresh: within this time it is returned without
162
+ * any request, also without a manifest request. After it, the copy is checked against the manifest (or, without
163
+ * a usable manifest, downloaded again). It is also the `revalidate` time of a read in Next.js. Defaults to 300
164
+ * (rulebook LIM-13).
165
+ */
166
+ ttlSeconds?: number;
167
+ /**
168
+ * How long, in seconds, one read of the manifest serves every copy that is checked, and the `revalidate` time
169
+ * of the manifest in Next.js. Defaults to 300.
170
+ */
171
+ manifestTtlSeconds?: number;
172
+ /**
173
+ * How long, in seconds, a copy is kept at most after it was downloaded. After it the copy is downloaded again,
174
+ * also when its hash did not change. Defaults to 86400 (24 hours).
175
+ */
176
+ maxAgeSeconds?: number;
177
+ /**
178
+ * The most bytes of proxied media that the media proxy keeps in memory, by file name and hash. The oldest
179
+ * files go first. Defaults to 52428800 (50 MB); `0` turns the media cache off.
180
+ */
181
+ mediaCacheMaxBytes?: number;
182
+ };
183
+ /**
184
+ * URL path prefix of the Next.js proxy route that serves production media
185
+ * same-origin (e.g. "/api/cms-media"). When set, getMedia returns a local
186
+ * proxy URL instead of the direct Ledger backend URL, which eliminates
187
+ * X-Frame-Options and CORS issues for all media types in the browser.
188
+ *
189
+ * The proxy route must be created in your Next.js app — run
190
+ * `npx parrel ledger init` to scaffold it automatically.
191
+ */
192
+ mediaProxyPath?: string;
193
+ /**
194
+ * Origin of the Parrel API, for example `http://localhost:18700` to test against a local backend.
195
+ *
196
+ * Leave it out to use the `PARREL_API_ORIGIN` environment variable or, when that is not set,
197
+ * `https://api.parrel.dev`. Apps that run only in the browser (React, Vue, Angular) cannot read
198
+ * environment variables, so pass the public variable of the framework here, for example
199
+ * `import.meta.env.VITE_PARREL_API_ORIGIN`. Only `https://` origins are allowed, except `http://` on
200
+ * `localhost`, `127.0.0.1` or `[::1]`; any other value throws a `ParrelError` with code `SD00100008`.
201
+ *
202
+ * @example
203
+ * ```ts
204
+ * defineParrelLedger({ slug: "your-service-slug", apiOrigin: "http://localhost:18700" });
205
+ * ```
206
+ */
207
+ apiOrigin?: string;
208
+ /**
209
+ * Origin of your own site, which a read from a server sends as its `Origin` header (rulebook LED-11, SEC-33).
210
+ * Ledger refuses a read from a public server without an allowed origin, and a browser sets its own, so only reads
211
+ * of the server adapter on a server use it: the manifest, a resource and the URL of a media field. Writes, the
212
+ * media proxy and `parrel ledger sync` never send it. Give an origin that is on the list of your Ledger service in
213
+ * the Parrel portal.
214
+ *
215
+ * Leave it out to use the `PARREL_SITE_ORIGIN` environment variable; there is no default. The value is trimmed, a
216
+ * bare domain gets `https://`, and it is sent in lower case without a trailing slash. `localhost` is allowed with
217
+ * `http://` or `https://` on any port; any other host must be `https://` without a port, a path or a query, or
218
+ * `defineParrelLedger` throws a `ParrelError` with code `SD00100018`. A read from a server in production or live
219
+ * mode with no site origin at all throws `SD00100019` before it sends anything. The mock needs none.
220
+ *
221
+ * @example
222
+ * ```ts
223
+ * defineParrelLedger({ slug: "your-service-slug", siteOrigin: "https://shop.be" });
224
+ * ```
225
+ */
226
+ siteOrigin?: string;
227
+ /**
228
+ * `"live"` makes Ledger use the Parrel service also in development, instead of the mock content. The
229
+ * environment variable `PARREL_FORCE_LIVE=1` does the same. Default `"auto"`: mock content outside
230
+ * production, the Parrel service in production.
231
+ *
232
+ * @example
233
+ * ```ts
234
+ * defineParrelLedger({ slug: "your-service-slug", mode: "live", apiOrigin: "http://localhost:18700" });
235
+ * ```
236
+ */
237
+ mode?: ParrelMode;
238
+ /**
239
+ * Sends the `X-Parrel-Package` header (`@parrel/ledger@<version>`) on calls from a browser too. Default `true`.
240
+ * Calls from a server and from the CLI always send it. Set it to `false` only when a proxy of your own between the
241
+ * browser and Ledger refuses the header.
242
+ *
243
+ * @example
244
+ * ```ts
245
+ * defineParrelLedger({ slug: "your-service-slug", sendHandshakeFromBrowser: false });
246
+ * ```
247
+ */
248
+ sendHandshakeFromBrowser?: boolean;
249
+ }
250
+ /**
251
+ * Options of {@link createParrelLedgerServerAdapter}.
252
+ */
253
+ export interface ParrelLedgerServerAdapterOptions {
254
+ /**
255
+ * Origin of the Parrel API, for example `http://localhost:18700`. See {@link DefineParrelLedgerConfig.apiOrigin}.
256
+ *
257
+ * @example
258
+ * ```ts
259
+ * createParrelLedgerServerAdapter({ apiOrigin: "http://localhost:18700" });
260
+ * ```
261
+ */
262
+ apiOrigin?: string;
263
+ /**
264
+ * Origin of your site, sent as `Origin` on the reads from a server. See {@link DefineParrelLedgerConfig.siteOrigin}.
265
+ *
266
+ * @example
267
+ * ```ts
268
+ * createParrelLedgerServerAdapter({ siteOrigin: "https://shop.be" });
269
+ * ```
270
+ */
271
+ siteOrigin?: string;
272
+ /**
273
+ * `"live"` makes the adapter behave like production also in development, so it sends the access token and
274
+ * uses the resource and media paths of the service. Default `"auto"`.
275
+ */
276
+ mode?: ParrelMode;
277
+ /** Sends the `X-Parrel-Package` header on browser calls too, unless `false`. See {@link DefineParrelLedgerConfig.sendHandshakeFromBrowser}. */
278
+ sendHandshakeFromBrowser?: boolean;
279
+ }
280
+ /**
281
+ * Internal normalized Ledger runtime configuration.
282
+ */
283
+ export interface ParrelLedgerRuntimeConfig extends DefineParrelLedgerConfig {
284
+ adapter: ParrelLedgerAdapter;
285
+ }
286
+ /**
287
+ * Options for mock adapter initialization
288
+ */
289
+ export interface MockAdapterByEnvOptions {
290
+ /**
291
+ * Path to mock.json file (e.g., "./parrel/ledger/mock.json")
292
+ */
293
+ file?: string;
294
+ /**
295
+ * Inline mock data. In a browser this is the content of the mock; on a server it is merged into the file store.
296
+ */
297
+ data?: MockAdapterData;
298
+ /**
299
+ * In a browser, the URL path below which `getMedia()` expects the media files. Defaults to `/parrel/ledger`.
300
+ * See {@link DefineParrelLedgerConfig.mockMediaPath}.
301
+ */
302
+ mockMediaPath?: string;
303
+ /**
304
+ * Fallback adapter to use in production (if mock is disabled)
305
+ */
306
+ fallbackAdapter?: ParrelLedgerAdapter;
307
+ /**
308
+ * Override NODE_ENV detection (for testing)
309
+ */
310
+ nodeEnv?: string;
311
+ /**
312
+ * Enable mock only in dev (default: true)
313
+ */
314
+ enableInDevOnly?: boolean;
315
+ /**
316
+ * URL path prefix under which mock media files are served during development.
317
+ * The Next.js app must have an API route at this path that reads from the mock media directory.
318
+ * Defaults to "/api/dev-cms-media".
319
+ */
320
+ devMediaServePath?: string;
321
+ /**
322
+ * Origin of the Parrel API for the production server adapter. See {@link DefineParrelLedgerConfig.apiOrigin}.
323
+ */
324
+ apiOrigin?: string;
325
+ /** Origin of your site for the production adapter. See {@link DefineParrelLedgerConfig.siteOrigin}. */
326
+ siteOrigin?: string;
327
+ /**
328
+ * `"live"` uses the Parrel service also in development. See {@link DefineParrelLedgerConfig.mode}.
329
+ */
330
+ mode?: ParrelMode;
331
+ /** Sends the `X-Parrel-Package` header on browser calls too, unless `false`. See {@link DefineParrelLedgerConfig.sendHandshakeFromBrowser}. */
332
+ sendHandshakeFromBrowser?: boolean;
333
+ }
334
+ /**
335
+ * Cache entry with TTL
336
+ */
337
+ export interface CacheEntry<T> {
338
+ value: T;
339
+ expiresAt: number;
340
+ }
341
+ /**
342
+ * Routes pattern for access control
343
+ */
344
+ export type LedgerRoutePatterns = string[] | "*";
345
+ /**
346
+ * Media field API - nested under ledgerClient.resource.fieldName
347
+ * Example: ledgerClient.home.heroImage.getMedia()
348
+ */
349
+ export interface MediaFieldApi {
350
+ getMedia(options?: ContentAccessOptions): Promise<string>;
351
+ setMedia(file: File): Promise<void>;
352
+ }
353
+ /**
354
+ * Content resource API - exposed as ledgerClient.resourceName
355
+ * T = the content type (e.g., HomePage)
356
+ * M = media field accessors (nested objects)
357
+ */
358
+ export interface ResourceApi<T, M extends Record<string, MediaFieldApi> = {}> {
359
+ getContent(options?: ContentAccessOptions): Promise<T>;
360
+ setContent(data: Partial<T>): Promise<void>;
361
+ }
362
+ /**
363
+ * Combined resource API with media field accessors
364
+ */
365
+ export type ResourceWithMedia<T, M extends Record<string, MediaFieldApi>> = ResourceApi<T, M> & M;
366
+ /**
367
+ * Cache mode for content and media retrieval.
368
+ *
369
+ * - "default": Read from cache first; on miss, fetch from adapter and cache result.
370
+ * Best for public pages (maximum performance).
371
+ * - "force": Skip cache read; always fetch fresh from adapter; update cache after fetch.
372
+ * Best for admin panels and preview mode (always accurate data).
373
+ * - "no-store": Skip cache read and write; fetch from adapter but don't persist to cache.
374
+ * Best for debugging and realtime dashboards (never cached).
375
+ */
376
+ export type CacheMode = "default" | "force" | "no-store";
377
+ /**
378
+ * Options for getContent and getMedia operations
379
+ */
380
+ export interface ContentAccessOptions {
381
+ /**
382
+ * Cache strategy for this request:
383
+ * - "default": Cache-first (read cache, fetch on miss, write to cache)
384
+ * - "force": Always fetch fresh, update cache
385
+ * - "no-store": Always fetch fresh, never write to cache
386
+ * @default "default"
387
+ */
388
+ cache?: CacheMode;
389
+ }
390
+ /** @deprecated Use {@link LedgerContentPath}. */
391
+ export type CmsContentPath = LedgerContentPath;
392
+ /** @deprecated Use {@link LedgerMediaPath}. */
393
+ export type CmsMediaPath = LedgerMediaPath;
394
+ /** @deprecated Use {@link LedgerFieldDefinition}. */
395
+ export type CmsFieldDefinition = LedgerFieldDefinition;
396
+ /** @deprecated Use {@link LedgerMapSchema}. */
397
+ export type CmsMapSchema = LedgerMapSchema;
398
+ /** @deprecated Use {@link ParrelLedgerAdapter}. */
399
+ export type ParrelCmsAdapter = ParrelLedgerAdapter;
400
+ /** @deprecated Use {@link DefineParrelLedgerConfig}. */
401
+ export type DefineParrelCmsConfig = DefineParrelLedgerConfig;
402
+ /** @deprecated Use {@link ParrelLedgerRuntimeConfig}. */
403
+ export type ParrelCmsRuntimeConfig = ParrelLedgerRuntimeConfig;
404
+ /** @deprecated Use {@link LedgerRoutePatterns}. */
405
+ export type CmsRoutePatterns = LedgerRoutePatterns;
406
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,11 @@
1
+ /** The seven field types of {@link LedgerFieldType}, for code that checks a map. */
2
+ export const LEDGER_FIELD_TYPES = [
3
+ "string",
4
+ "number",
5
+ "boolean",
6
+ "media",
7
+ "media-reference",
8
+ "array",
9
+ "object",
10
+ ];
11
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAyCA,oFAAoF;AACpF,MAAM,CAAC,MAAM,kBAAkB,GAA+B;IAC7D,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,OAAO;IACP,iBAAiB;IACjB,OAAO;IACP,QAAQ;CACR,CAAC"}
@@ -0,0 +1,5 @@
1
+ import type { LedgerKnownErrorCode } from "../core/error-codes.generated.js";
2
+ import type { ErrorMessage } from "./types.js";
3
+ /** The name, status, message and advice of every code of @parrel/ledger. Used by `getErrorInfo()`. */
4
+ export declare const LEDGER_ERROR_MESSAGES: Readonly<Record<LedgerKnownErrorCode, ErrorMessage>>;
5
+ //# sourceMappingURL=error-messages.generated.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"error-messages.generated.d.ts","sourceRoot":"","sources":["../../src/errors/error-messages.generated.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,sGAAsG;AACtG,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,oBAAoB,EAAE,YAAY,CAAC,CAu8BtF,CAAC"}