@mailwoman/api 9.0.0 → 9.1.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 (6) hide show
  1. package/out/schema.d.ts +106 -2
  2. package/out/schema.d.ts.map +1 -1
  3. package/out/schema.js +69 -0
  4. package/out/schema.js.map +1 -1
  5. package/package.json +5 -5
  6. package/schema.ts +74 -0
package/out/schema.d.ts CHANGED
@@ -99,12 +99,39 @@ export declare const GeocodeRequestSchema: z.ZodObject<{
99
99
  */
100
100
  export declare const GeocodeOutcomeSchema: z.ZodObject<{
101
101
  input: z.ZodString;
102
+ components: z.ZodRecord<z.ZodEnum<{
103
+ country: "country";
104
+ region: "region";
105
+ locality: "locality";
106
+ dependent_locality: "dependent_locality";
107
+ postcode: "postcode";
108
+ subregion: "subregion";
109
+ house_number: "house_number";
110
+ street: "street";
111
+ street_prefix: "street_prefix";
112
+ street_prefix_particle: "street_prefix_particle";
113
+ street_suffix: "street_suffix";
114
+ intersection_a: "intersection_a";
115
+ intersection_b: "intersection_b";
116
+ unit: "unit";
117
+ venue: "venue";
118
+ attention: "attention";
119
+ po_box: "po_box";
120
+ cedex: "cedex";
121
+ prefecture: "prefecture";
122
+ municipality: "municipality";
123
+ district: "district";
124
+ block: "block";
125
+ sub_block: "sub_block";
126
+ building_number: "building_number";
127
+ building_name: "building_name";
128
+ }> & z.core.$partial, z.ZodString>;
102
129
  lat: z.ZodNullable<z.ZodNumber>;
103
130
  lon: z.ZodNullable<z.ZodNumber>;
104
131
  resolution_tier: z.ZodEnum<{
132
+ street: "street";
105
133
  address_point: "address_point";
106
134
  interpolated: "interpolated";
107
- street: "street";
108
135
  admin: "admin";
109
136
  }>;
110
137
  uncertainty_m: z.ZodNullable<z.ZodNumber>;
@@ -134,6 +161,31 @@ export declare const GeocodeOutcomeSchema: z.ZodObject<{
134
161
  placeID: z.ZodOptional<z.ZodString>;
135
162
  }, z.core.$strip>>;
136
163
  postcode_country_scope: z.ZodNullable<z.ZodString>;
164
+ intent_markers: z.ZodArray<z.ZodObject<{
165
+ kind: z.ZodEnum<{
166
+ intersection: "intersection";
167
+ po_box: "po_box";
168
+ postcode_only: "postcode_only";
169
+ locality_only: "locality_only";
170
+ structured_address: "structured_address";
171
+ landmark: "landmark";
172
+ poi_query: "poi_query";
173
+ vague: "vague";
174
+ bare_toponym: "bare_toponym";
175
+ route_pair: "route_pair";
176
+ near_me: "near_me";
177
+ poi_category: "poi_category";
178
+ }>;
179
+ code: z.ZodEnum<{
180
+ poi_category: "poi_category";
181
+ declared_ambiguity: "declared_ambiguity";
182
+ declared_fork: "declared_fork";
183
+ focus_point_required: "focus_point_required";
184
+ }>;
185
+ mechanism: z.ZodString;
186
+ message: z.ZodString;
187
+ evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
188
+ }, z.core.$strip>>;
137
189
  }, z.core.$loose>;
138
190
  /**
139
191
  * `POST /v1/batch` request body.
@@ -151,12 +203,39 @@ export declare const BatchRequestSchema: z.ZodObject<{
151
203
  export declare const BatchResponseSchema: z.ZodObject<{
152
204
  results: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
153
205
  input: z.ZodString;
206
+ components: z.ZodRecord<z.ZodEnum<{
207
+ country: "country";
208
+ region: "region";
209
+ locality: "locality";
210
+ dependent_locality: "dependent_locality";
211
+ postcode: "postcode";
212
+ subregion: "subregion";
213
+ house_number: "house_number";
214
+ street: "street";
215
+ street_prefix: "street_prefix";
216
+ street_prefix_particle: "street_prefix_particle";
217
+ street_suffix: "street_suffix";
218
+ intersection_a: "intersection_a";
219
+ intersection_b: "intersection_b";
220
+ unit: "unit";
221
+ venue: "venue";
222
+ attention: "attention";
223
+ po_box: "po_box";
224
+ cedex: "cedex";
225
+ prefecture: "prefecture";
226
+ municipality: "municipality";
227
+ district: "district";
228
+ block: "block";
229
+ sub_block: "sub_block";
230
+ building_number: "building_number";
231
+ building_name: "building_name";
232
+ }> & z.core.$partial, z.ZodString>;
154
233
  lat: z.ZodNullable<z.ZodNumber>;
155
234
  lon: z.ZodNullable<z.ZodNumber>;
156
235
  resolution_tier: z.ZodEnum<{
236
+ street: "street";
157
237
  address_point: "address_point";
158
238
  interpolated: "interpolated";
159
- street: "street";
160
239
  admin: "admin";
161
240
  }>;
162
241
  uncertainty_m: z.ZodNullable<z.ZodNumber>;
@@ -186,6 +265,31 @@ export declare const BatchResponseSchema: z.ZodObject<{
186
265
  placeID: z.ZodOptional<z.ZodString>;
187
266
  }, z.core.$strip>>;
188
267
  postcode_country_scope: z.ZodNullable<z.ZodString>;
268
+ intent_markers: z.ZodArray<z.ZodObject<{
269
+ kind: z.ZodEnum<{
270
+ intersection: "intersection";
271
+ po_box: "po_box";
272
+ postcode_only: "postcode_only";
273
+ locality_only: "locality_only";
274
+ structured_address: "structured_address";
275
+ landmark: "landmark";
276
+ poi_query: "poi_query";
277
+ vague: "vague";
278
+ bare_toponym: "bare_toponym";
279
+ route_pair: "route_pair";
280
+ near_me: "near_me";
281
+ poi_category: "poi_category";
282
+ }>;
283
+ code: z.ZodEnum<{
284
+ poi_category: "poi_category";
285
+ declared_ambiguity: "declared_ambiguity";
286
+ declared_fork: "declared_fork";
287
+ focus_point_required: "focus_point_required";
288
+ }>;
289
+ mechanism: z.ZodString;
290
+ message: z.ZodString;
291
+ evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
292
+ }, z.core.$strip>>;
189
293
  }, z.core.$loose>, z.ZodObject<{
190
294
  input: z.ZodString;
191
295
  error: z.ZodString;
package/out/schema.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AAErC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAEnD;;GAEG;AACH;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;EAA2D,CAAA;AAEvF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,OAAO,CAAA;AAEtC;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;iBAMN,CAAA;AAEzB;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;iBAA6E,CAAA;AAE9G;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;iBAON,CAAA;AAEzB;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;iBAKN,CAAA;AAiC3B;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BN,CAAA;AAE3B;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;iBAUN,CAAA;AAYzB;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAIN,CAAA;AAE1B;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;iBAKN,CAAA;AAE3B;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;iBAIN,CAAA;AAQ5B;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;iBAMN,CAAA;AAE1B;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;iBAKN,CAAA;AAE3B;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;iBAMN,CAAA"}
1
+ {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AAErC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAEnD;;GAEG;AACH;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;EAA2D,CAAA;AAEvF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,OAAO,CAAA;AAEtC;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;iBAMN,CAAA;AAEzB;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;iBAA6E,CAAA;AAE9G;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;iBAON,CAAA;AAEzB;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;iBAKN,CAAA;AAuG3B;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+BN,CAAA;AAE3B;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;iBAUN,CAAA;AAYzB;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAIN,CAAA;AAE1B;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;iBAKN,CAAA;AAE3B;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;iBAIN,CAAA;AAQ5B;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;iBAMN,CAAA;AAE1B;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;iBAKN,CAAA;AAE3B;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;iBAMN,CAAA"}
package/out/schema.js CHANGED
@@ -105,6 +105,71 @@ const GeocodeCandidateSchema = z
105
105
  placeID: z.string().optional(),
106
106
  })
107
107
  .openapi("GeocodeCandidate");
108
+ /**
109
+ * Canonical parsed-component map carried by `GeocodeResult.components`. Spelled out at this engine-agnostic API
110
+ * boundary for the same reason the result schema is hand-modeled; the compile-time drift pin in
111
+ * `mailwoman/test/api-schema-drift.test.ts` catches any mismatch with the real `ComponentTag`-keyed result type.
112
+ */
113
+ const GeocodeComponentsSchema = z.partialRecord(z.enum([
114
+ "country",
115
+ "region",
116
+ "locality",
117
+ "dependent_locality",
118
+ "postcode",
119
+ "subregion",
120
+ "house_number",
121
+ "street",
122
+ "street_prefix",
123
+ "street_prefix_particle",
124
+ "street_suffix",
125
+ "intersection_a",
126
+ "intersection_b",
127
+ "unit",
128
+ "venue",
129
+ "attention",
130
+ "po_box",
131
+ "cedex",
132
+ "prefecture",
133
+ "municipality",
134
+ "district",
135
+ "block",
136
+ "sub_block",
137
+ "building_number",
138
+ "building_name",
139
+ ]), z.string());
140
+ /**
141
+ * One `GeocodeOutcome.intent_markers` entry — an advisory the ROAD_TO_V9 §4 intent vocabulary raised about the QUERY.
142
+ * Mirrors `QueryIntentMarker` (`core/pipeline/types.ts`).
143
+ *
144
+ * `evidence` is deliberately open (`z.record`): each `code` carries its own measurement — a dominance margin, a pair of
145
+ * interpretations, a taxonomy id — and flattening those into one closed shape would either lose the numbers or invent
146
+ * fields that do not apply. `code` is the discriminator a client branches on.
147
+ */
148
+ const QueryIntentMarkerSchema = z
149
+ .object({
150
+ // Spelled out rather than `z.string()` so `mailwoman/test/api-schema-drift.test.ts`'s schema-too-wide direction
151
+ // keeps biting: a new `QueryKind` that never reaches this list is a documented contract that has quietly stopped
152
+ // describing the real one.
153
+ kind: z.enum([
154
+ "postcode_only",
155
+ "locality_only",
156
+ "structured_address",
157
+ "intersection",
158
+ "po_box",
159
+ "landmark",
160
+ "poi_query",
161
+ "vague",
162
+ "bare_toponym",
163
+ "route_pair",
164
+ "near_me",
165
+ "poi_category",
166
+ ]),
167
+ code: z.enum(["declared_ambiguity", "declared_fork", "focus_point_required", "poi_category"]),
168
+ mechanism: z.string(),
169
+ message: z.string(),
170
+ evidence: z.record(z.string(), z.unknown()).optional(),
171
+ })
172
+ .openapi("QueryIntentMarker");
108
173
  /**
109
174
  * `POST /v1/geocode` response — a hand-modeled mirror of `GeocodeResult`'s wire shape (`mailwoman/geocode-core.ts`),
110
175
  * `.loose()` so a field the engine adds that this schema doesn't yet know about still rides through undocumented rather
@@ -118,6 +183,7 @@ const GeocodeCandidateSchema = z
118
183
  export const GeocodeOutcomeSchema = z
119
184
  .object({
120
185
  input: z.string(),
186
+ components: GeocodeComponentsSchema,
121
187
  lat: z.number().nullable(),
122
188
  lon: z.number().nullable(),
123
189
  resolution_tier: z.enum(["address_point", "interpolated", "street", "admin"]),
@@ -140,6 +206,9 @@ export const GeocodeOutcomeSchema = z
140
206
  // OVERRODE the request's country prior — so a caller who asked for US and got an FR answer can see which
141
207
  // evidence bought the change instead of reading it as a bug.
142
208
  postcode_country_scope: z.string().nullable(),
209
+ // ROAD_TO_V9 §4: query-intent advisories. Always present; empty means the vocabulary looked and had nothing to
210
+ // say. Advisory ONLY — no marker changed which answer won, and a client is free to ignore the array entirely.
211
+ intent_markers: z.array(QueryIntentMarkerSchema),
143
212
  })
144
213
  .loose()
145
214
  .openapi("GeocodeOutcome");
package/out/schema.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"schema.js","sourceRoot":"","sources":["../schema.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"schema.js","sourceRoot":"","sources":["../schema.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mailwoman/api",
3
- "version": "9.0.0",
3
+ "version": "9.1.0",
4
4
  "description": "The native Mailwoman HTTP API — engine-agnostic /v1 surface (parse, geocode, batch, resolve, format) with health, metrics, and an emitted OpenAPI document.",
5
5
  "license": "AGPL-3.0-only OR LicenseRef-Commercial",
6
6
  "repository": {
@@ -43,10 +43,10 @@
43
43
  },
44
44
  "dependencies": {
45
45
  "@hono/zod-openapi": "^1.5.1",
46
- "@mailwoman/api-kit": "9.0.0",
47
- "@mailwoman/core": "9.0.0",
48
- "@mailwoman/formatter": "9.0.0",
49
- "hono": "^4.12.32",
46
+ "@mailwoman/api-kit": "9.1.0",
47
+ "@mailwoman/core": "9.1.0",
48
+ "@mailwoman/formatter": "9.1.0",
49
+ "hono": "^4.13.0",
50
50
  "zod": "^4.4.3"
51
51
  }
52
52
  }
package/schema.ts CHANGED
@@ -116,6 +116,76 @@ const GeocodeCandidateSchema = z
116
116
  })
117
117
  .openapi("GeocodeCandidate")
118
118
 
119
+ /**
120
+ * Canonical parsed-component map carried by `GeocodeResult.components`. Spelled out at this engine-agnostic API
121
+ * boundary for the same reason the result schema is hand-modeled; the compile-time drift pin in
122
+ * `mailwoman/test/api-schema-drift.test.ts` catches any mismatch with the real `ComponentTag`-keyed result type.
123
+ */
124
+ const GeocodeComponentsSchema = z.partialRecord(
125
+ z.enum([
126
+ "country",
127
+ "region",
128
+ "locality",
129
+ "dependent_locality",
130
+ "postcode",
131
+ "subregion",
132
+ "house_number",
133
+ "street",
134
+ "street_prefix",
135
+ "street_prefix_particle",
136
+ "street_suffix",
137
+ "intersection_a",
138
+ "intersection_b",
139
+ "unit",
140
+ "venue",
141
+ "attention",
142
+ "po_box",
143
+ "cedex",
144
+ "prefecture",
145
+ "municipality",
146
+ "district",
147
+ "block",
148
+ "sub_block",
149
+ "building_number",
150
+ "building_name",
151
+ ]),
152
+ z.string()
153
+ )
154
+
155
+ /**
156
+ * One `GeocodeOutcome.intent_markers` entry — an advisory the ROAD_TO_V9 §4 intent vocabulary raised about the QUERY.
157
+ * Mirrors `QueryIntentMarker` (`core/pipeline/types.ts`).
158
+ *
159
+ * `evidence` is deliberately open (`z.record`): each `code` carries its own measurement — a dominance margin, a pair of
160
+ * interpretations, a taxonomy id — and flattening those into one closed shape would either lose the numbers or invent
161
+ * fields that do not apply. `code` is the discriminator a client branches on.
162
+ */
163
+ const QueryIntentMarkerSchema = z
164
+ .object({
165
+ // Spelled out rather than `z.string()` so `mailwoman/test/api-schema-drift.test.ts`'s schema-too-wide direction
166
+ // keeps biting: a new `QueryKind` that never reaches this list is a documented contract that has quietly stopped
167
+ // describing the real one.
168
+ kind: z.enum([
169
+ "postcode_only",
170
+ "locality_only",
171
+ "structured_address",
172
+ "intersection",
173
+ "po_box",
174
+ "landmark",
175
+ "poi_query",
176
+ "vague",
177
+ "bare_toponym",
178
+ "route_pair",
179
+ "near_me",
180
+ "poi_category",
181
+ ]),
182
+ code: z.enum(["declared_ambiguity", "declared_fork", "focus_point_required", "poi_category"]),
183
+ mechanism: z.string(),
184
+ message: z.string(),
185
+ evidence: z.record(z.string(), z.unknown()).optional(),
186
+ })
187
+ .openapi("QueryIntentMarker")
188
+
119
189
  /**
120
190
  * `POST /v1/geocode` response — a hand-modeled mirror of `GeocodeResult`'s wire shape (`mailwoman/geocode-core.ts`),
121
191
  * `.loose()` so a field the engine adds that this schema doesn't yet know about still rides through undocumented rather
@@ -129,6 +199,7 @@ const GeocodeCandidateSchema = z
129
199
  export const GeocodeOutcomeSchema = z
130
200
  .object({
131
201
  input: z.string(),
202
+ components: GeocodeComponentsSchema,
132
203
  lat: z.number().nullable(),
133
204
  lon: z.number().nullable(),
134
205
  resolution_tier: z.enum(["address_point", "interpolated", "street", "admin"]),
@@ -151,6 +222,9 @@ export const GeocodeOutcomeSchema = z
151
222
  // OVERRODE the request's country prior — so a caller who asked for US and got an FR answer can see which
152
223
  // evidence bought the change instead of reading it as a bug.
153
224
  postcode_country_scope: z.string().nullable(),
225
+ // ROAD_TO_V9 §4: query-intent advisories. Always present; empty means the vocabulary looked and had nothing to
226
+ // say. Advisory ONLY — no marker changed which answer won, and a client is free to ignore the array entirely.
227
+ intent_markers: z.array(QueryIntentMarkerSchema),
154
228
  })
155
229
  .loose()
156
230
  .openapi("GeocodeOutcome")