@greatwait/contracts 0.1.0-alpha.5 → 0.1.0-alpha.7

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 (135) hide show
  1. package/README.md +1 -1
  2. package/dist/attempt-diagnostics.d.ts +8 -0
  3. package/dist/attempt-diagnostics.js +68 -0
  4. package/dist/authority.d.ts +4 -1
  5. package/dist/authority.js +1 -0
  6. package/dist/billing.d.ts +11 -10
  7. package/dist/billing.js +7 -4
  8. package/dist/data-export.d.ts +2 -0
  9. package/dist/delivery.d.ts +43 -40
  10. package/dist/delivery.js +14 -37
  11. package/dist/effective-limits.d.ts +4 -4
  12. package/dist/endpoints.d.ts +173 -5
  13. package/dist/endpoints.js +72 -1
  14. package/dist/first-value-journey.js +4 -4
  15. package/dist/http-request.d.ts +193 -0
  16. package/dist/http-request.js +305 -0
  17. package/dist/identity.d.ts +7 -7
  18. package/dist/index.d.ts +6 -3
  19. package/dist/index.js +5 -2
  20. package/dist/mcp.d.ts +2 -1
  21. package/dist/members.d.ts +141 -0
  22. package/dist/members.js +223 -0
  23. package/dist/oauth.d.ts +7 -0
  24. package/dist/operation-definitions.d.ts +20 -4
  25. package/dist/operation-definitions.js +9 -1
  26. package/dist/operations.d.ts +999 -135
  27. package/dist/operations.js +83 -10
  28. package/dist/organization-lifecycle.d.ts +10 -0
  29. package/dist/policy.js +5 -2
  30. package/dist/scheduling-records.d.ts +332 -8
  31. package/dist/scheduling-records.js +5 -0
  32. package/dist/scheduling.d.ts +485 -18
  33. package/dist/scheduling.js +77 -5
  34. package/dist/secrets.d.ts +7 -0
  35. package/dist/signatures.d.ts +1 -1
  36. package/dist/tenancy.d.ts +1 -1
  37. package/dist/tenancy.js +1 -1
  38. package/dist/test-sink.d.ts +27 -41
  39. package/dist/test-sink.js +12 -31
  40. package/dist/zod-values.d.ts +2 -2
  41. package/dist/zod-values.js +1 -1
  42. package/generated/v1/callback-receiver.json +4 -4
  43. package/generated/v1/examples/endpoints.ensure.request.json +3 -0
  44. package/generated/v1/examples/endpoints.ensure.response.json +20 -0
  45. package/generated/v1/examples/invitations.create.request.json +5 -0
  46. package/generated/v1/examples/invitations.create.response.json +7 -0
  47. package/generated/v1/examples/invitations.list.response.json +11 -0
  48. package/generated/v1/examples/invitations.resend.request.json +1 -0
  49. package/generated/v1/examples/invitations.resend.response.json +4 -0
  50. package/generated/v1/examples/invitations.revoke.request.json +3 -0
  51. package/generated/v1/examples/invitations.revoke.response.json +4 -0
  52. package/generated/v1/examples/members.list.response.json +13 -0
  53. package/generated/v1/examples/members.remove.request.json +3 -0
  54. package/generated/v1/examples/members.remove.response.json +4 -0
  55. package/generated/v1/examples/members.role.request.json +3 -0
  56. package/generated/v1/examples/members.role.response.json +4 -0
  57. package/generated/v1/examples/projectmembers.add.request.json +1 -0
  58. package/generated/v1/examples/projectmembers.add.response.json +4 -0
  59. package/generated/v1/examples/projectmembers.remove.request.json +3 -0
  60. package/generated/v1/examples/projectmembers.remove.response.json +4 -0
  61. package/generated/v1/first-value-journey.json +4 -4
  62. package/generated/v1/manifest.json +284 -0
  63. package/generated/v1/openapi.json +9387 -1021
  64. package/generated/v1/policy-matrix.json +72 -0
  65. package/generated/v1/schemas/attempts.list.response.json +105 -0
  66. package/generated/v1/schemas/attempts.read.response.json +105 -0
  67. package/generated/v1/schemas/billing.notices.response.json +16 -6
  68. package/generated/v1/schemas/context.read.response.json +1 -0
  69. package/generated/v1/schemas/credentials.connection.response.json +1 -0
  70. package/generated/v1/schemas/credentials.create.request.json +1 -0
  71. package/generated/v1/schemas/credentials.create.response.json +1 -0
  72. package/generated/v1/schemas/credentials.list.response.json +1 -0
  73. package/generated/v1/schemas/credentials.revoke.response.json +1 -0
  74. package/generated/v1/schemas/credentials.rotate.response.json +2 -0
  75. package/generated/v1/schemas/endpoints.acknowledgeSigningKeyRotation.response.json +59 -0
  76. package/generated/v1/schemas/endpoints.create.request.json +74 -0
  77. package/generated/v1/schemas/endpoints.create.response.json +59 -0
  78. package/generated/v1/schemas/endpoints.disable.response.json +59 -0
  79. package/generated/v1/schemas/endpoints.enable.response.json +59 -0
  80. package/generated/v1/schemas/endpoints.ensure.request.json +91 -0
  81. package/generated/v1/schemas/endpoints.ensure.response.json +169 -0
  82. package/generated/v1/schemas/endpoints.list.response.json +59 -0
  83. package/generated/v1/schemas/endpoints.read.response.json +59 -0
  84. package/generated/v1/schemas/endpoints.rotateSigningKey.response.json +59 -0
  85. package/generated/v1/schemas/endpoints.update.request.json +74 -0
  86. package/generated/v1/schemas/endpoints.update.response.json +59 -0
  87. package/generated/v1/schemas/grants.list.response.json +1 -0
  88. package/generated/v1/schemas/grants.revoke.response.json +1 -0
  89. package/generated/v1/schemas/invitations.create.request-headers.json +13 -0
  90. package/generated/v1/schemas/invitations.create.request.json +24 -0
  91. package/generated/v1/schemas/invitations.create.response.json +31 -0
  92. package/generated/v1/schemas/invitations.list.response.json +40 -0
  93. package/generated/v1/schemas/invitations.resend.request-headers.json +13 -0
  94. package/generated/v1/schemas/invitations.resend.request.json +6 -0
  95. package/generated/v1/schemas/invitations.resend.response.json +27 -0
  96. package/generated/v1/schemas/invitations.revoke.request-headers.json +13 -0
  97. package/generated/v1/schemas/invitations.revoke.request.json +12 -0
  98. package/generated/v1/schemas/invitations.revoke.response.json +27 -0
  99. package/generated/v1/schemas/members.list.response.json +53 -0
  100. package/generated/v1/schemas/members.remove.request-headers.json +13 -0
  101. package/generated/v1/schemas/members.remove.request.json +12 -0
  102. package/generated/v1/schemas/members.remove.response.json +27 -0
  103. package/generated/v1/schemas/members.role.request-headers.json +13 -0
  104. package/generated/v1/schemas/members.role.request.json +12 -0
  105. package/generated/v1/schemas/members.role.response.json +27 -0
  106. package/generated/v1/schemas/occurrences.redeliver.response.json +105 -0
  107. package/generated/v1/schemas/projectmembers.add.request-headers.json +13 -0
  108. package/generated/v1/schemas/projectmembers.add.request.json +6 -0
  109. package/generated/v1/schemas/projectmembers.add.response.json +27 -0
  110. package/generated/v1/schemas/projectmembers.remove.request-headers.json +13 -0
  111. package/generated/v1/schemas/projectmembers.remove.request.json +12 -0
  112. package/generated/v1/schemas/projectmembers.remove.response.json +27 -0
  113. package/generated/v1/schemas/schedules.archive.response.json +188 -1
  114. package/generated/v1/schemas/schedules.cancel.response.json +188 -1
  115. package/generated/v1/schemas/schedules.create.request.json +164 -1
  116. package/generated/v1/schemas/schedules.create.response.json +206 -1
  117. package/generated/v1/schemas/schedules.list.response.json +188 -1
  118. package/generated/v1/schemas/schedules.pause.response.json +188 -1
  119. package/generated/v1/schemas/schedules.read.response.json +188 -1
  120. package/generated/v1/schemas/schedules.replace.request.json +164 -1
  121. package/generated/v1/schemas/schedules.replace.response.json +206 -1
  122. package/generated/v1/schemas/schedules.resume.response.json +188 -1
  123. package/generated/v1/snippets/endpoints.create.json +1 -1
  124. package/generated/v1/snippets/endpoints.ensure.json +6 -0
  125. package/generated/v1/snippets/invitations.create.json +6 -0
  126. package/generated/v1/snippets/invitations.list.json +6 -0
  127. package/generated/v1/snippets/invitations.resend.json +6 -0
  128. package/generated/v1/snippets/invitations.revoke.json +6 -0
  129. package/generated/v1/snippets/journey/create-destination.json +1 -1
  130. package/generated/v1/snippets/members.list.json +6 -0
  131. package/generated/v1/snippets/members.remove.json +6 -0
  132. package/generated/v1/snippets/members.role.json +6 -0
  133. package/generated/v1/snippets/projectmembers.add.json +6 -0
  134. package/generated/v1/snippets/projectmembers.remove.json +6 -0
  135. package/package.json +1 -1
@@ -15,8 +15,8 @@ import { z } from "./zod.js";
15
15
  */
16
16
  export declare const CALLBACK_ENDPOINT_STATUSES: readonly ["active", "disabled"];
17
17
  export declare const callbackEndpointStatusSchema: import("zod").ZodEnum<{
18
- disabled: "disabled";
19
18
  active: "active";
19
+ disabled: "disabled";
20
20
  }>;
21
21
  export type CallbackEndpointStatus = z.infer<typeof callbackEndpointStatusSchema>;
22
22
  /**
@@ -83,6 +83,19 @@ export declare const callbackEndpointNameSchema: import("zod").ZodString;
83
83
  * field, so list/get/update/disable/enable cannot accidentally recover it.
84
84
  */
85
85
  export declare const callbackEndpointSchema: import("zod").ZodObject<{
86
+ headers: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodUnion<readonly [import("zod").ZodObject<{
87
+ name: import("zod").ZodString;
88
+ secret: import("zod").ZodLiteral<false>;
89
+ value: import("zod").ZodString;
90
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
91
+ name: import("zod").ZodString;
92
+ secret: import("zod").ZodLiteral<true>;
93
+ configured: import("zod").ZodLiteral<true>;
94
+ value: import("zod").ZodOptional<import("zod").ZodNever>;
95
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
96
+ name: import("zod").ZodString;
97
+ suppressed: import("zod").ZodLiteral<true>;
98
+ }, import("zod/v4/core").$strict>]>>>;
86
99
  createdAt: import("zod").ZodString;
87
100
  disabledAt: import("zod").ZodOptional<import("zod").ZodString>;
88
101
  environmentKind: import("zod").ZodEnum<{
@@ -101,8 +114,8 @@ export declare const callbackEndpointSchema: import("zod").ZodObject<{
101
114
  }, import("zod/v4/core").$strip>>;
102
115
  }, import("zod/v4/core").$strip>;
103
116
  status: import("zod").ZodEnum<{
104
- disabled: "disabled";
105
117
  active: "active";
118
+ disabled: "disabled";
106
119
  }>;
107
120
  updatedAt: import("zod").ZodString;
108
121
  url: import("zod").ZodString;
@@ -111,6 +124,19 @@ export declare const callbackEndpointSchema: import("zod").ZodObject<{
111
124
  export type CallbackEndpoint = z.infer<typeof callbackEndpointSchema>;
112
125
  export declare const callbackEndpointPageSchema: import("zod").ZodObject<{
113
126
  data: import("zod").ZodArray<import("zod").ZodObject<{
127
+ headers: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodUnion<readonly [import("zod").ZodObject<{
128
+ name: import("zod").ZodString;
129
+ secret: import("zod").ZodLiteral<false>;
130
+ value: import("zod").ZodString;
131
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
132
+ name: import("zod").ZodString;
133
+ secret: import("zod").ZodLiteral<true>;
134
+ configured: import("zod").ZodLiteral<true>;
135
+ value: import("zod").ZodOptional<import("zod").ZodNever>;
136
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
137
+ name: import("zod").ZodString;
138
+ suppressed: import("zod").ZodLiteral<true>;
139
+ }, import("zod/v4/core").$strict>]>>>;
114
140
  createdAt: import("zod").ZodString;
115
141
  disabledAt: import("zod").ZodOptional<import("zod").ZodString>;
116
142
  environmentKind: import("zod").ZodEnum<{
@@ -129,8 +155,8 @@ export declare const callbackEndpointPageSchema: import("zod").ZodObject<{
129
155
  }, import("zod/v4/core").$strip>>;
130
156
  }, import("zod/v4/core").$strip>;
131
157
  status: import("zod").ZodEnum<{
132
- disabled: "disabled";
133
158
  active: "active";
159
+ disabled: "disabled";
134
160
  }>;
135
161
  updatedAt: import("zod").ZodString;
136
162
  url: import("zod").ZodString;
@@ -148,6 +174,19 @@ export declare const callbackEndpointPageSchema: import("zod").ZodObject<{
148
174
  export type CallbackEndpointPage = z.infer<typeof callbackEndpointPageSchema>;
149
175
  /** The one response that carries the per-endpoint secret. */
150
176
  export declare const callbackEndpointCreatedSchema: import("zod").ZodObject<{
177
+ headers: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodUnion<readonly [import("zod").ZodObject<{
178
+ name: import("zod").ZodString;
179
+ secret: import("zod").ZodLiteral<false>;
180
+ value: import("zod").ZodString;
181
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
182
+ name: import("zod").ZodString;
183
+ secret: import("zod").ZodLiteral<true>;
184
+ configured: import("zod").ZodLiteral<true>;
185
+ value: import("zod").ZodOptional<import("zod").ZodNever>;
186
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
187
+ name: import("zod").ZodString;
188
+ suppressed: import("zod").ZodLiteral<true>;
189
+ }, import("zod/v4/core").$strict>]>>>;
151
190
  createdAt: import("zod").ZodString;
152
191
  disabledAt: import("zod").ZodOptional<import("zod").ZodString>;
153
192
  environmentKind: import("zod").ZodEnum<{
@@ -166,8 +205,8 @@ export declare const callbackEndpointCreatedSchema: import("zod").ZodObject<{
166
205
  }, import("zod/v4/core").$strip>>;
167
206
  }, import("zod/v4/core").$strip>;
168
207
  status: import("zod").ZodEnum<{
169
- disabled: "disabled";
170
208
  active: "active";
209
+ disabled: "disabled";
171
210
  }>;
172
211
  updatedAt: import("zod").ZodString;
173
212
  url: import("zod").ZodString;
@@ -183,6 +222,19 @@ export declare const callbackSigningKeyRotationRequestSchema: import("zod").ZodO
183
222
  export type CallbackSigningKeyRotationRequest = z.infer<typeof callbackSigningKeyRotationRequestSchema>;
184
223
  export declare const callbackEndpointRotatedSchema: import("zod").ZodObject<{
185
224
  endpoint: import("zod").ZodObject<{
225
+ headers: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodUnion<readonly [import("zod").ZodObject<{
226
+ name: import("zod").ZodString;
227
+ secret: import("zod").ZodLiteral<false>;
228
+ value: import("zod").ZodString;
229
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
230
+ name: import("zod").ZodString;
231
+ secret: import("zod").ZodLiteral<true>;
232
+ configured: import("zod").ZodLiteral<true>;
233
+ value: import("zod").ZodOptional<import("zod").ZodNever>;
234
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
235
+ name: import("zod").ZodString;
236
+ suppressed: import("zod").ZodLiteral<true>;
237
+ }, import("zod/v4/core").$strict>]>>>;
186
238
  createdAt: import("zod").ZodString;
187
239
  disabledAt: import("zod").ZodOptional<import("zod").ZodString>;
188
240
  environmentKind: import("zod").ZodEnum<{
@@ -201,8 +253,8 @@ export declare const callbackEndpointRotatedSchema: import("zod").ZodObject<{
201
253
  }, import("zod/v4/core").$strip>>;
202
254
  }, import("zod/v4/core").$strip>;
203
255
  status: import("zod").ZodEnum<{
204
- disabled: "disabled";
205
256
  active: "active";
257
+ disabled: "disabled";
206
258
  }>;
207
259
  updatedAt: import("zod").ZodString;
208
260
  url: import("zod").ZodString;
@@ -239,7 +291,123 @@ export declare const callbackEndpointSigningSecretsSchema: import("zod").ZodObje
239
291
  }, import("zod/v4/core").$strip>>;
240
292
  }, import("zod/v4/core").$strip>;
241
293
  export type CallbackEndpointSigningSecrets = z.infer<typeof callbackEndpointSigningSecretsSchema>;
294
+ /**
295
+ * Where an endpoint's signing secret is, for a result that does not carry it
296
+ * (W9-44, FXO-2907).
297
+ *
298
+ * `endpoints.ensure`, and a schedule write that names a `url` instead of an
299
+ * endpoint, may bring an endpoint into existence without handing its secret
300
+ * to the caller. An agent working over MCP is the reason: anything a tool
301
+ * returns lands in ordinary tool history, so the secret is never in the
302
+ * result. What is in it is where a person finds the secret — the endpoint's
303
+ * own page, where a signed-in member reveals it — so the agent can pass that
304
+ * on rather than leave the person to discover that deliveries are signed.
305
+ *
306
+ * `returned` is the literal `false` rather than an absent field because a
307
+ * reader deciding whether it holds a secret should be told so, not left to
308
+ * infer it from what is missing.
309
+ */
310
+ export declare const signingSecretNoticeSchema: import("zod").ZodObject<{
311
+ guidance: import("zod").ZodString;
312
+ returned: import("zod").ZodLiteral<false>;
313
+ revealUrl: import("zod").ZodOptional<import("zod").ZodString>;
314
+ }, import("zod/v4/core").$strip>;
315
+ export type SigningSecretNotice = z.infer<typeof signingSecretNoticeSchema>;
316
+ /**
317
+ * The dashboard path of one endpoint's page, beneath the project and
318
+ * environment it belongs to. The dashboard's router serves it; a test there
319
+ * holds the two to the same shape.
320
+ */
321
+ export declare function endpointDashboardPath(target: {
322
+ readonly endpoint: string;
323
+ readonly environmentKind: string;
324
+ /**
325
+ * The organization **as the dashboard addresses it**: the sign-in
326
+ * provider's organization, not GreatWait's `org_…` identifier.
327
+ */
328
+ readonly organization: string;
329
+ readonly project: string;
330
+ }): string;
331
+ /**
332
+ * The notice a secretless endpoint result carries. `dashboardOrigin` is the
333
+ * deployment's dashboard; without one the notice still says where to look.
334
+ */
335
+ export declare function signingSecretNotice(target: Parameters<typeof endpointDashboardPath>[0], dashboardOrigin: string | undefined): SigningSecretNotice;
336
+ /**
337
+ * What `endpoints.ensure` answers: the endpoint at the requested address,
338
+ * whether this call created it, and where its signing secret is.
339
+ *
340
+ * Metadata only, like every endpoint read. There is no `secret` field to fill
341
+ * by mistake; the shape is what keeps it out of an agent's history.
342
+ */
343
+ export declare const callbackEndpointEnsuredSchema: import("zod").ZodObject<{
344
+ headers: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodUnion<readonly [import("zod").ZodObject<{
345
+ name: import("zod").ZodString;
346
+ secret: import("zod").ZodLiteral<false>;
347
+ value: import("zod").ZodString;
348
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
349
+ name: import("zod").ZodString;
350
+ secret: import("zod").ZodLiteral<true>;
351
+ configured: import("zod").ZodLiteral<true>;
352
+ value: import("zod").ZodOptional<import("zod").ZodNever>;
353
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
354
+ name: import("zod").ZodString;
355
+ suppressed: import("zod").ZodLiteral<true>;
356
+ }, import("zod/v4/core").$strict>]>>>;
357
+ createdAt: import("zod").ZodString;
358
+ disabledAt: import("zod").ZodOptional<import("zod").ZodString>;
359
+ environmentKind: import("zod").ZodEnum<{
360
+ test: "test";
361
+ live: "live";
362
+ }>;
363
+ id: import("zod").ZodString;
364
+ name: import("zod").ZodOptional<import("zod").ZodString>;
365
+ project: import("zod").ZodString;
366
+ signingKeys: import("zod").ZodObject<{
367
+ current: import("zod").ZodString;
368
+ next: import("zod").ZodOptional<import("zod").ZodObject<{
369
+ acknowledgedAt: import("zod").ZodOptional<import("zod").ZodString>;
370
+ id: import("zod").ZodString;
371
+ overlapEndsAt: import("zod").ZodString;
372
+ }, import("zod/v4/core").$strip>>;
373
+ }, import("zod/v4/core").$strip>;
374
+ status: import("zod").ZodEnum<{
375
+ active: "active";
376
+ disabled: "disabled";
377
+ }>;
378
+ updatedAt: import("zod").ZodString;
379
+ url: import("zod").ZodString;
380
+ version: import("zod").ZodNumber;
381
+ created: import("zod").ZodBoolean;
382
+ signingSecret: import("zod").ZodObject<{
383
+ guidance: import("zod").ZodString;
384
+ returned: import("zod").ZodLiteral<false>;
385
+ revealUrl: import("zod").ZodOptional<import("zod").ZodString>;
386
+ }, import("zod/v4/core").$strip>;
387
+ }, import("zod/v4/core").$strip>;
388
+ export type CallbackEndpointEnsured = z.infer<typeof callbackEndpointEnsuredSchema>;
389
+ /**
390
+ * A callback destination as a caller types it: HTTPS on port 443, no
391
+ * credentials or fragment, a public name or address. The DNS half of the
392
+ * policy runs when an endpoint is created at it.
393
+ */
394
+ export declare function callbackUrlSchema(): import("zod").ZodString;
242
395
  export declare const callbackEndpointRequestSchema: import("zod").ZodObject<{
396
+ headers: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
397
+ action: import("zod").ZodLiteral<"set">;
398
+ name: import("zod").ZodString;
399
+ value: import("zod").ZodString;
400
+ secret: import("zod").ZodOptional<import("zod").ZodBoolean>;
401
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
402
+ action: import("zod").ZodLiteral<"keep">;
403
+ name: import("zod").ZodString;
404
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
405
+ action: import("zod").ZodLiteral<"remove">;
406
+ name: import("zod").ZodString;
407
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
408
+ action: import("zod").ZodLiteral<"suppress">;
409
+ name: import("zod").ZodString;
410
+ }, import("zod/v4/core").$strict>], "action">>>;
243
411
  name: import("zod").ZodOptional<import("zod").ZodString>;
244
412
  url: import("zod").ZodString;
245
413
  }, import("zod/v4/core").$strip>;
package/dist/endpoints.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { endpointHeaderChangesSchema, publicHttpHeaderSchema, } from "./http-request.js";
1
2
  import { z } from "./zod.js";
2
3
  import { environmentKindSchema } from "./authority.js";
3
4
  import { evaluateCallbackUrl } from "./callback-safety.js";
@@ -89,6 +90,7 @@ export const callbackEndpointNameSchema = z
89
90
  * field, so list/get/update/disable/enable cannot accidentally recover it.
90
91
  */
91
92
  export const callbackEndpointSchema = z.object({
93
+ headers: z.array(publicHttpHeaderSchema).optional(),
92
94
  createdAt: timestampSchema,
93
95
  disabledAt: timestampSchema.optional(),
94
96
  environmentKind: environmentKindSchema,
@@ -148,7 +150,75 @@ export const callbackEndpointSigningSecretsSchema = z.object({
148
150
  .extend({ overlapEndsAt: timestampSchema })
149
151
  .optional(),
150
152
  });
151
- function callbackUrlSchema() {
153
+ /**
154
+ * Where an endpoint's signing secret is, for a result that does not carry it
155
+ * (W9-44, FXO-2907).
156
+ *
157
+ * `endpoints.ensure`, and a schedule write that names a `url` instead of an
158
+ * endpoint, may bring an endpoint into existence without handing its secret
159
+ * to the caller. An agent working over MCP is the reason: anything a tool
160
+ * returns lands in ordinary tool history, so the secret is never in the
161
+ * result. What is in it is where a person finds the secret — the endpoint's
162
+ * own page, where a signed-in member reveals it — so the agent can pass that
163
+ * on rather than leave the person to discover that deliveries are signed.
164
+ *
165
+ * `returned` is the literal `false` rather than an absent field because a
166
+ * reader deciding whether it holds a secret should be told so, not left to
167
+ * infer it from what is missing.
168
+ */
169
+ export const signingSecretNoticeSchema = z.object({
170
+ /** One sentence an agent can relay to the person it is working for. */
171
+ guidance: z.string().min(1),
172
+ /** Never `true`: these results do not carry the secret. */
173
+ returned: z.literal(false),
174
+ /**
175
+ * The endpoint's page in the GreatWait dashboard, where a signed-in member
176
+ * reveals the secret. Absent only where this deployment has no dashboard.
177
+ */
178
+ revealUrl: z.string().url().optional(),
179
+ });
180
+ /**
181
+ * The dashboard path of one endpoint's page, beneath the project and
182
+ * environment it belongs to. The dashboard's router serves it; a test there
183
+ * holds the two to the same shape.
184
+ */
185
+ export function endpointDashboardPath(target) {
186
+ return `/o/${encodeURIComponent(target.organization)}/p/${encodeURIComponent(target.project)}/${encodeURIComponent(target.environmentKind)}/settings/endpoints/${encodeURIComponent(target.endpoint)}`;
187
+ }
188
+ /**
189
+ * The notice a secretless endpoint result carries. `dashboardOrigin` is the
190
+ * deployment's dashboard; without one the notice still says where to look.
191
+ */
192
+ export function signingSecretNotice(target, dashboardOrigin) {
193
+ return {
194
+ guidance: "GreatWait signs every callback to this endpoint. The signing secret is never returned here; a signed-in member of the project reveals it on the endpoint's page in the GreatWait dashboard, and your receiver uses it to verify that a callback came from GreatWait.",
195
+ returned: false,
196
+ ...(dashboardOrigin === undefined
197
+ ? {}
198
+ : {
199
+ revealUrl: new URL(endpointDashboardPath(target), dashboardOrigin)
200
+ .href,
201
+ }),
202
+ };
203
+ }
204
+ /**
205
+ * What `endpoints.ensure` answers: the endpoint at the requested address,
206
+ * whether this call created it, and where its signing secret is.
207
+ *
208
+ * Metadata only, like every endpoint read. There is no `secret` field to fill
209
+ * by mistake; the shape is what keeps it out of an agent's history.
210
+ */
211
+ export const callbackEndpointEnsuredSchema = callbackEndpointSchema.extend({
212
+ /** Whether this call created the endpoint, or found one already there. */
213
+ created: z.boolean(),
214
+ signingSecret: signingSecretNoticeSchema,
215
+ });
216
+ /**
217
+ * A callback destination as a caller types it: HTTPS on port 443, no
218
+ * credentials or fragment, a public name or address. The DNS half of the
219
+ * policy runs when an endpoint is created at it.
220
+ */
221
+ export function callbackUrlSchema() {
152
222
  return z
153
223
  .string()
154
224
  .url()
@@ -164,6 +234,7 @@ function callbackUrlSchema() {
164
234
  });
165
235
  }
166
236
  export const callbackEndpointRequestSchema = z.object({
237
+ headers: endpointHeaderChangesSchema.optional(),
167
238
  /**
168
239
  * A name for people (W4-14, FXO-2255). Omitted on a create, the endpoint
169
240
  * takes its whole URL as its name; omitted on an update, the stored name
@@ -109,7 +109,7 @@ export const CURL_JOURNEY_TOOLS = [
109
109
  ];
110
110
  export const FIRST_VALUE_PREREQUISITES = [
111
111
  {
112
- action: "Accept your GreatWait invitation, sign in, and create a project in the dashboard.",
112
+ action: "Sign up at https://app.greatwait.dev/sign-up and name your organization, or sign in. Then create a project in the dashboard, or pick an existing one.",
113
113
  because: "projects.create accepts only a signed-in member, so a project is created by a person rather than by an API credential.",
114
114
  id: "project",
115
115
  title: "A project",
@@ -121,10 +121,10 @@ export const FIRST_VALUE_PREREQUISITES = [
121
121
  title: "An API credential",
122
122
  },
123
123
  {
124
- action: "Have an HTTPS URL of your own that answers POST with a 2xx status, and can be reached from the public internet.",
125
- because: "GreatWait delivers your callback to an address you control. It does not offer a shared receiver to try, and it will not send your payload to a third-party inspection service on your behalf.",
124
+ action: "Get a test URL from webhook.site, which shows every request it receives, or use your own app's HTTPS URL. It must answer with a 2xx status and be reachable from the public internet.",
125
+ because: "GreatWait calls the URL you give it. Don't send real data to a public tester.",
126
126
  id: "receiver",
127
- title: "An HTTPS receiver you control",
127
+ title: "A URL to call",
128
128
  },
129
129
  ];
130
130
  export const FIRST_VALUE_VARIABLES = [
@@ -0,0 +1,193 @@
1
+ import { z } from "./zod.js";
2
+ export declare const HTTP_HEADER_BOUNDS: {
3
+ readonly count: 32;
4
+ readonly nameBytes: 128;
5
+ readonly valueBytes: 8192;
6
+ readonly totalBytes: 16384;
7
+ };
8
+ export declare const HTTP_METHODS: readonly ["POST", "PUT", "GET"];
9
+ /** Platform-owned authentication, content and transport fields cannot be overridden. */
10
+ export declare function reservedHttpHeaderReason(name: string): string | undefined;
11
+ export declare const httpHeaderNameSchema: import("zod").ZodString;
12
+ export declare const httpHeaderValueSchema: import("zod").ZodString;
13
+ export declare const headerChangeSchema: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
14
+ action: import("zod").ZodLiteral<"set">;
15
+ name: import("zod").ZodString;
16
+ value: import("zod").ZodString;
17
+ secret: import("zod").ZodOptional<import("zod").ZodBoolean>;
18
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
19
+ action: import("zod").ZodLiteral<"keep">;
20
+ name: import("zod").ZodString;
21
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
22
+ action: import("zod").ZodLiteral<"remove">;
23
+ name: import("zod").ZodString;
24
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
25
+ action: import("zod").ZodLiteral<"suppress">;
26
+ name: import("zod").ZodString;
27
+ }, import("zod/v4/core").$strict>], "action">;
28
+ export type HeaderChange = z.infer<typeof headerChangeSchema>;
29
+ export declare const headerChangesSchema: import("zod").ZodArray<import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
30
+ action: import("zod").ZodLiteral<"set">;
31
+ name: import("zod").ZodString;
32
+ value: import("zod").ZodString;
33
+ secret: import("zod").ZodOptional<import("zod").ZodBoolean>;
34
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
35
+ action: import("zod").ZodLiteral<"keep">;
36
+ name: import("zod").ZodString;
37
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
38
+ action: import("zod").ZodLiteral<"remove">;
39
+ name: import("zod").ZodString;
40
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
41
+ action: import("zod").ZodLiteral<"suppress">;
42
+ name: import("zod").ZodString;
43
+ }, import("zod/v4/core").$strict>], "action">>;
44
+ export declare const endpointHeaderChangesSchema: import("zod").ZodArray<import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
45
+ action: import("zod").ZodLiteral<"set">;
46
+ name: import("zod").ZodString;
47
+ value: import("zod").ZodString;
48
+ secret: import("zod").ZodOptional<import("zod").ZodBoolean>;
49
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
50
+ action: import("zod").ZodLiteral<"keep">;
51
+ name: import("zod").ZodString;
52
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
53
+ action: import("zod").ZodLiteral<"remove">;
54
+ name: import("zod").ZodString;
55
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
56
+ action: import("zod").ZodLiteral<"suppress">;
57
+ name: import("zod").ZodString;
58
+ }, import("zod/v4/core").$strict>], "action">>;
59
+ export declare const publicHttpHeaderSchema: import("zod").ZodUnion<readonly [import("zod").ZodObject<{
60
+ name: import("zod").ZodString;
61
+ secret: import("zod").ZodLiteral<false>;
62
+ value: import("zod").ZodString;
63
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
64
+ name: import("zod").ZodString;
65
+ secret: import("zod").ZodLiteral<true>;
66
+ configured: import("zod").ZodLiteral<true>;
67
+ value: import("zod").ZodOptional<import("zod").ZodNever>;
68
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
69
+ name: import("zod").ZodString;
70
+ suppressed: import("zod").ZodLiteral<true>;
71
+ }, import("zod/v4/core").$strict>]>;
72
+ export type PublicHttpHeader = z.infer<typeof publicHttpHeaderSchema>;
73
+ export declare const httpRequestSchema: import("zod").ZodObject<{
74
+ method: import("zod").ZodOptional<import("zod").ZodEnum<{
75
+ POST: "POST";
76
+ PUT: "PUT";
77
+ GET: "GET";
78
+ }>>;
79
+ body: import("zod").ZodOptional<import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
80
+ mode: import("zod").ZodLiteral<"envelope">;
81
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
82
+ mode: import("zod").ZodLiteral<"json">;
83
+ value: import("zod").ZodJSONSchema;
84
+ }, import("zod/v4/core").$strict>], "mode">>;
85
+ headers: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
86
+ action: import("zod").ZodLiteral<"set">;
87
+ name: import("zod").ZodString;
88
+ value: import("zod").ZodString;
89
+ secret: import("zod").ZodOptional<import("zod").ZodBoolean>;
90
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
91
+ action: import("zod").ZodLiteral<"keep">;
92
+ name: import("zod").ZodString;
93
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
94
+ action: import("zod").ZodLiteral<"remove">;
95
+ name: import("zod").ZodString;
96
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
97
+ action: import("zod").ZodLiteral<"suppress">;
98
+ name: import("zod").ZodString;
99
+ }, import("zod/v4/core").$strict>], "action">>>;
100
+ }, import("zod/v4/core").$strict>;
101
+ export type HttpRequest = z.infer<typeof httpRequestSchema>;
102
+ export declare const publicHttpRequestSchema: import("zod").ZodObject<{
103
+ method: import("zod").ZodEnum<{
104
+ POST: "POST";
105
+ PUT: "PUT";
106
+ GET: "GET";
107
+ }>;
108
+ body: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
109
+ mode: import("zod").ZodLiteral<"envelope">;
110
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
111
+ mode: import("zod").ZodLiteral<"none">;
112
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
113
+ mode: import("zod").ZodLiteral<"json">;
114
+ value: import("zod").ZodOptional<import("zod").ZodJSONSchema>;
115
+ }, import("zod/v4/core").$strict>], "mode">;
116
+ headers: import("zod").ZodArray<import("zod").ZodUnion<readonly [import("zod").ZodObject<{
117
+ name: import("zod").ZodString;
118
+ secret: import("zod").ZodLiteral<false>;
119
+ value: import("zod").ZodString;
120
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
121
+ name: import("zod").ZodString;
122
+ secret: import("zod").ZodLiteral<true>;
123
+ configured: import("zod").ZodLiteral<true>;
124
+ value: import("zod").ZodOptional<import("zod").ZodNever>;
125
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
126
+ name: import("zod").ZodString;
127
+ suppressed: import("zod").ZodLiteral<true>;
128
+ }, import("zod/v4/core").$strict>]>>;
129
+ }, import("zod/v4/core").$strict>;
130
+ export type PublicHttpRequest = z.infer<typeof publicHttpRequestSchema>;
131
+ export declare const storedHttpHeaderSchema: import("zod").ZodUnion<readonly [import("zod").ZodObject<{
132
+ name: import("zod").ZodString;
133
+ secret: import("zod").ZodLiteral<false>;
134
+ value: import("zod").ZodString;
135
+ valueBytes: import("zod").ZodNumber;
136
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
137
+ name: import("zod").ZodString;
138
+ secret: import("zod").ZodLiteral<true>;
139
+ envelope: import("zod").ZodObject<{
140
+ keyId: import("zod").ZodLiteral<"v1">;
141
+ nonce: import("zod").ZodString;
142
+ ciphertext: import("zod").ZodString;
143
+ }, import("zod/v4/core").$strict>;
144
+ valueBytes: import("zod").ZodNumber;
145
+ ownerKind: import("zod").ZodEnum<{
146
+ endpoint: "endpoint";
147
+ schedule: "schedule";
148
+ }>;
149
+ ownerId: import("zod").ZodString;
150
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
151
+ name: import("zod").ZodString;
152
+ suppressed: import("zod").ZodLiteral<true>;
153
+ }, import("zod/v4/core").$strict>]>;
154
+ export declare const storedHttpRequestSchema: import("zod").ZodObject<{
155
+ method: import("zod").ZodEnum<{
156
+ POST: "POST";
157
+ PUT: "PUT";
158
+ GET: "GET";
159
+ }>;
160
+ bodyMode: import("zod").ZodEnum<{
161
+ envelope: "envelope";
162
+ json: "json";
163
+ none: "none";
164
+ }>;
165
+ headers: import("zod").ZodArray<import("zod").ZodUnion<readonly [import("zod").ZodObject<{
166
+ name: import("zod").ZodString;
167
+ secret: import("zod").ZodLiteral<false>;
168
+ value: import("zod").ZodString;
169
+ valueBytes: import("zod").ZodNumber;
170
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
171
+ name: import("zod").ZodString;
172
+ secret: import("zod").ZodLiteral<true>;
173
+ envelope: import("zod").ZodObject<{
174
+ keyId: import("zod").ZodLiteral<"v1">;
175
+ nonce: import("zod").ZodString;
176
+ ciphertext: import("zod").ZodString;
177
+ }, import("zod/v4/core").$strict>;
178
+ valueBytes: import("zod").ZodNumber;
179
+ ownerKind: import("zod").ZodEnum<{
180
+ endpoint: "endpoint";
181
+ schedule: "schedule";
182
+ }>;
183
+ ownerId: import("zod").ZodString;
184
+ }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
185
+ name: import("zod").ZodString;
186
+ suppressed: import("zod").ZodLiteral<true>;
187
+ }, import("zod/v4/core").$strict>]>>;
188
+ encryptedTemplate: import("zod").ZodOptional<import("zod").ZodObject<{
189
+ keyId: import("zod").ZodLiteral<"v1">;
190
+ nonce: import("zod").ZodString;
191
+ ciphertext: import("zod").ZodString;
192
+ }, import("zod/v4/core").$strict>>;
193
+ }, import("zod/v4/core").$strict>;