@geekmidas/events 10.0.0-alpha.13 → 10.0.0-alpha.131

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 (86) hide show
  1. package/README.md +46 -1
  2. package/dist/{SQSSubscriber-cpo624qU.mjs → SQSSubscriber-BEJBfNTe.mjs} +94 -10
  3. package/dist/SQSSubscriber-BEJBfNTe.mjs.map +1 -0
  4. package/dist/{SQSSubscriber-DLPZCzFE.cjs → SQSSubscriber-COTqWvOk.cjs} +101 -10
  5. package/dist/SQSSubscriber-COTqWvOk.cjs.map +1 -0
  6. package/dist/basic/index.cjs +35 -4
  7. package/dist/basic/index.cjs.map +1 -1
  8. package/dist/basic/index.d.cts +8 -1
  9. package/dist/basic/index.d.cts.map +1 -1
  10. package/dist/basic/index.d.mts +8 -1
  11. package/dist/basic/index.d.mts.map +1 -1
  12. package/dist/basic/index.mjs +35 -5
  13. package/dist/basic/index.mjs.map +1 -1
  14. package/dist/index.cjs +45 -141
  15. package/dist/index.cjs.map +1 -1
  16. package/dist/index.d.cts +80 -20
  17. package/dist/index.d.cts.map +1 -1
  18. package/dist/index.d.mts +80 -20
  19. package/dist/index.d.mts.map +1 -1
  20. package/dist/index.mjs +33 -141
  21. package/dist/index.mjs.map +1 -1
  22. package/dist/pgboss/index.cjs +124 -27
  23. package/dist/pgboss/index.cjs.map +1 -1
  24. package/dist/pgboss/index.d.cts +51 -4
  25. package/dist/pgboss/index.d.cts.map +1 -1
  26. package/dist/pgboss/index.d.mts +51 -4
  27. package/dist/pgboss/index.d.mts.map +1 -1
  28. package/dist/pgboss/index.mjs +121 -27
  29. package/dist/pgboss/index.mjs.map +1 -1
  30. package/dist/rabbitmq/index.cjs +63 -20
  31. package/dist/rabbitmq/index.cjs.map +1 -1
  32. package/dist/rabbitmq/index.d.cts +15 -1
  33. package/dist/rabbitmq/index.d.cts.map +1 -1
  34. package/dist/rabbitmq/index.d.mts +15 -1
  35. package/dist/rabbitmq/index.d.mts.map +1 -1
  36. package/dist/rabbitmq/index.mjs +63 -20
  37. package/dist/rabbitmq/index.mjs.map +1 -1
  38. package/dist/registry-DIx25Q5s.d.cts +255 -0
  39. package/dist/registry-DIx25Q5s.d.cts.map +1 -0
  40. package/dist/registry-DIx25Q5s.d.mts +255 -0
  41. package/dist/registry-DIx25Q5s.d.mts.map +1 -0
  42. package/dist/registry-DXLY1Xf6.mjs +99 -0
  43. package/dist/registry-DXLY1Xf6.mjs.map +1 -0
  44. package/dist/registry-DlT36229.cjs +122 -0
  45. package/dist/registry-DlT36229.cjs.map +1 -0
  46. package/dist/sns/index.cjs +439 -12
  47. package/dist/sns/index.cjs.map +1 -1
  48. package/dist/sns/index.d.cts +263 -8
  49. package/dist/sns/index.d.cts.map +1 -1
  50. package/dist/sns/index.d.mts +263 -8
  51. package/dist/sns/index.d.mts.map +1 -1
  52. package/dist/sns/index.mjs +423 -13
  53. package/dist/sns/index.mjs.map +1 -1
  54. package/dist/sns/snsUrl.d.cts.map +1 -1
  55. package/dist/sns/snsUrl.d.mts.map +1 -1
  56. package/dist/sqs/index.cjs +22 -55
  57. package/dist/sqs/index.cjs.map +1 -1
  58. package/dist/sqs/index.d.cts +23 -1
  59. package/dist/sqs/index.d.cts.map +1 -1
  60. package/dist/sqs/index.d.mts +23 -1
  61. package/dist/sqs/index.d.mts.map +1 -1
  62. package/dist/sqs/index.mjs +20 -53
  63. package/dist/sqs/index.mjs.map +1 -1
  64. package/dist/sqs/sqsUrl.d.cts.map +1 -1
  65. package/dist/sqs/sqsUrl.d.mts.map +1 -1
  66. package/dist/telemetry-DG3l807O.cjs +309 -0
  67. package/dist/telemetry-DG3l807O.cjs.map +1 -0
  68. package/dist/telemetry-DjjgJMul.mjs +244 -0
  69. package/dist/telemetry-DjjgJMul.mjs.map +1 -0
  70. package/package.json +8 -3
  71. package/dist/PgBossConnection-CywKoAZU.cjs +0 -2
  72. package/dist/PgBossConnection-DjoqT84r.mjs +0 -2
  73. package/dist/RabbitMQConnection-C9eccBL8.cjs +0 -2
  74. package/dist/RabbitMQConnection-CAp7VqyT.mjs +0 -2
  75. package/dist/SNSConnection-BWDC1wAF.cjs +0 -2
  76. package/dist/SNSConnection-ezQvVrDv.mjs +0 -2
  77. package/dist/SQSSubscriber-DLPZCzFE.cjs.map +0 -1
  78. package/dist/SQSSubscriber-cpo624qU.mjs.map +0 -1
  79. package/dist/types-C15FC0qp.mjs +0 -18
  80. package/dist/types-C15FC0qp.mjs.map +0 -1
  81. package/dist/types-DXNwyRyg.cjs +0 -23
  82. package/dist/types-DXNwyRyg.cjs.map +0 -1
  83. package/dist/types-lnM-qoe_.d.cts +0 -140
  84. package/dist/types-lnM-qoe_.d.cts.map +0 -1
  85. package/dist/types-lnM-qoe_.d.mts +0 -140
  86. package/dist/types-lnM-qoe_.d.mts.map +0 -1
@@ -1,16 +1,24 @@
1
- import { i as EventSubscriber, n as EventPublisher, r as EventPublisherType, s as PublishableMessage, t as EventConnection } from "../types-lnM-qoe_.cjs";
1
+ import { d as EventPublisher, f as EventPublisherType, g as PublishableMessage, p as EventSubscriber, t as EventsDriver, u as EventConnection } from "../registry-DIx25Q5s.cjs";
2
2
  import { SnsAddress, t as snsUrl_d_exports } from "./snsUrl.cjs";
3
- import { SNSClient } from "@aws-sdk/client-sns";
3
+ import { SNSClient, SNSClientConfig } from "@aws-sdk/client-sns";
4
+ //#region src/sns/driver.d.ts
5
+ /**
6
+ * `sns://` — an SNS topic, consumed through an SQS queue subscribed to it.
7
+ * Register it with `registerEventsDriver(snsEventsDriver)`; an AWS entry
8
+ * registers `sqsEventsDriver` beside it.
9
+ */
10
+ export declare const snsEventsDriver: EventsDriver;
11
+ //#endregion
4
12
  //#region src/sns/SNSConnection.d.ts
5
13
  interface SNSConnectionConfig {
6
14
  topicArn: string;
7
15
  region?: string;
8
16
  endpoint?: string;
9
- credentials?: {
10
- accessKeyId: string;
11
- secretAccessKey: string;
12
- sessionToken?: string;
13
- };
17
+ /**
18
+ * Static keys, or a provider the SDK resolves them through — a deploy's
19
+ * profile or chain, where nothing pins a key pair.
20
+ */
21
+ credentials?: SNSClientConfig['credentials'];
14
22
  }
15
23
  export declare class SNSConnection implements EventConnection {
16
24
  readonly type = EventPublisherType.SNS;
@@ -36,6 +44,245 @@ export declare class SNSConnection implements EventConnection {
36
44
  get topicArn(): string;
37
45
  }
38
46
  //#endregion
47
+ //#region src/sns/push.d.ts
48
+ /**
49
+ * SNS delivering to an HTTP(S) endpoint, rather than to a queue that is polled.
50
+ *
51
+ * SNS POSTs each message to the subscribed URL as JSON. That is the whole
52
+ * transport: no queue in between, no poller, and the endpoint is handed the
53
+ * same envelope a Lambda subscription receives inside `Records[].Sns` — so the
54
+ * handler that runs deployed can be the one that runs here.
55
+ *
56
+ * The endpoint is public, so a message is trusted only once its signature
57
+ * checks out against a certificate SNS itself serves. Anything else that POSTs
58
+ * there is somebody's guess at the shape.
59
+ */
60
+ /** A message SNS POSTs to a subscribed HTTP endpoint. */
61
+ interface SnsHttpMessage {
62
+ Type: 'Notification' | 'SubscriptionConfirmation' | 'UnsubscribeConfirmation';
63
+ MessageId: string;
64
+ TopicArn: string;
65
+ Message: string;
66
+ Timestamp: string;
67
+ SignatureVersion: string;
68
+ Signature: string;
69
+ SigningCertURL: string;
70
+ Subject?: string;
71
+ /** Confirmation messages only. */
72
+ Token?: string;
73
+ /** Confirmation messages only: GET it to confirm. */
74
+ SubscribeURL?: string;
75
+ /** Notifications only. */
76
+ UnsubscribeURL?: string;
77
+ MessageAttributes?: Record<string, {
78
+ Type: string;
79
+ Value: string;
80
+ }>;
81
+ }
82
+ interface VerifySnsMessageOptions {
83
+ /**
84
+ * Fetch the PEM at a certificate URL. `fetch` by default; replaceable so a
85
+ * test signs with its own key instead of SNS's.
86
+ */
87
+ fetchCertificate?: (url: string) => Promise<string>;
88
+ }
89
+ /** The string SNS signed for this message. */
90
+ export declare function snsStringToSign(message: SnsHttpMessage): string;
91
+ /**
92
+ * Check that SNS sent this message: the certificate is SNS's own, and the
93
+ * signature over the message's signed fields verifies against it.
94
+ *
95
+ * Throws rather than returning false, so a caller cannot forget to look.
96
+ */
97
+ export declare function verifySnsMessage(message: SnsHttpMessage, options?: VerifySnsMessageOptions): Promise<void>;
98
+ /**
99
+ * Confirm a subscription by visiting the URL SNS sent. Until this happens SNS
100
+ * delivers nothing to the endpoint.
101
+ */
102
+ export declare function confirmSnsSubscription(message: SnsHttpMessage, request?: (url: string) => Promise<{
103
+ ok: boolean;
104
+ status: number;
105
+ }>): Promise<void>;
106
+ /** Where a subscription's filter policy is matched. */
107
+ type SnsFilterPolicyScope = 'MessageAttributes' | 'MessageBody';
108
+ /** What an HTTP subscription is created or brought up to date with. */
109
+ interface HttpSubscriptionFilter {
110
+ /**
111
+ * The event types this endpoint takes. Becomes the subscription's filter
112
+ * policy on the `type` attribute `SNSPublisher` sets, so SNS sends nothing
113
+ * else — fan-out to every subscriber, each seeing only what it named.
114
+ *
115
+ * Absent, with no {@link filterPolicy} either, for a topic whose
116
+ * publisher sets no `type` — a bucket's — whose subscriber filters what it
117
+ * is sent.
118
+ *
119
+ * Ignored when {@link filterPolicy} is given.
120
+ */
121
+ events?: readonly string[];
122
+ /**
123
+ * A filter policy of the caller's own, for messages SNS did not receive
124
+ * from `SNSPublisher` — a bucket's notifications carry no `type` attribute,
125
+ * so they are matched on their body instead.
126
+ */
127
+ filterPolicy?: Record<string, unknown>;
128
+ /** Where {@link filterPolicy} is matched. `MessageAttributes` by default. */
129
+ filterPolicyScope?: SnsFilterPolicyScope;
130
+ /**
131
+ * An SQS queue's ARN for what SNS gives up delivering. SNS retries an HTTP
132
+ * endpoint for a limited time and then drops the message, so without one an
133
+ * outage longer than that loses events.
134
+ */
135
+ deadLetterQueueArn?: string;
136
+ }
137
+ interface SubscribeHttpEndpointOptions extends HttpSubscriptionFilter {
138
+ /** The URL SNS POSTs to — `http:` or `https:`, which picks the protocol. */
139
+ endpoint: string;
140
+ }
141
+ /**
142
+ * Subscribe an HTTP endpoint to the connection's topic, converging on one
143
+ * confirmed subscription with the filter asked for — so it is safe on every
144
+ * start. What a server does against an emulator, where nothing deploys it;
145
+ * against SNS itself the deploy owns the subscription
146
+ * ({@link reconcileHttpSubscriptions}).
147
+ *
148
+ * - **none yet** — subscribed; SNS sends a confirmation to the endpoint.
149
+ * - **confirmed** — its filter and dead-letter queue are brought up to date.
150
+ * Subscribing again with different attributes is an error on SNS, and the
151
+ * events a subscriber names change.
152
+ * - **stuck pending** — a confirmation that never landed (the endpoint was
153
+ * down, or answered wrong). Subscribing the same endpoint again is a no-op
154
+ * on an emulator, so it is dropped and subscribed afresh, which sends a new
155
+ * confirmation.
156
+ */
157
+ export declare function subscribeHttpEndpoint(connection: SNSConnection, options: SubscribeHttpEndpointOptions): Promise<string | undefined>;
158
+ /** One endpoint the deploy wants subscribed, under the name it is recorded by. */
159
+ interface HttpSubscriptionSpec extends HttpSubscriptionFilter {
160
+ /** What the ARN is recorded under — the subscriber's export. */
161
+ name: string;
162
+ /** The URL SNS POSTs to. */
163
+ endpoint: string;
164
+ }
165
+ interface ReconcileHttpSubscriptionsOptions {
166
+ /** Every endpoint that should be subscribed to the topic. */
167
+ endpoints: readonly HttpSubscriptionSpec[];
168
+ /**
169
+ * The host these endpoints answer on. A subscription to an endpoint on it
170
+ * that is not in {@link endpoints} — a subscriber renamed or removed — is
171
+ * unsubscribed; anything subscribed on another host is somebody else's and
172
+ * left alone.
173
+ */
174
+ ownedHost: string;
175
+ }
176
+ interface ReconciledHttpSubscriptions {
177
+ /** Each endpoint's subscription ARN, by its name — stable across runs. */
178
+ subscriptions: Record<string, string>;
179
+ /** The names whose subscription SNS still waits to have confirmed. */
180
+ pending: string[];
181
+ /** The ARNs of what was unsubscribed as no longer wanted. */
182
+ removed: string[];
183
+ }
184
+ /**
185
+ * Converge a topic's HTTP subscriptions on the endpoints a deploy wants, and
186
+ * answer each one's ARN for the deploy to record and hand to the server.
187
+ *
188
+ * The deploy's half of push delivery against SNS itself: the server never
189
+ * subscribes, so its credentials need no `sns:Subscribe` — and the only
190
+ * subscriptions to the topic are ones the deploy made.
191
+ *
192
+ * Run it twice: once before the server starts, for the ARNs it is configured
193
+ * with — SNS answers one even while the subscription waits to be confirmed —
194
+ * and once the server is up, which subscribes each still-pending endpoint
195
+ * again so SNS resends its confirmation to a server now there to answer it.
196
+ * The ARN does not change between the two.
197
+ *
198
+ * - **absent** — subscribed with its filter.
199
+ * - **present** — its filter and dead-letter queue are brought up to date;
200
+ * pending, it is subscribed again to resend the confirmation.
201
+ * - **stale** — on {@link ReconcileHttpSubscriptionsOptions.ownedHost} and no
202
+ * longer wanted: unsubscribed. (A stale one SNS still lists as pending has
203
+ * no ARN to act on; SNS drops it unconfirmed after three days.)
204
+ */
205
+ export declare function reconcileHttpSubscriptions(connection: SNSConnection, options: ReconcileHttpSubscriptionsOptions): Promise<ReconciledHttpSubscriptions>;
206
+ /**
207
+ * Confirm a subscription through the API, as its topic's owner, rather than by
208
+ * visiting the URL SNS sent.
209
+ *
210
+ * `AuthenticateOnUnsubscribe` is the point of it. A subscription confirmed by
211
+ * visiting `SubscribeURL` can be removed by anyone holding the
212
+ * `UnsubscribeURL` every notification carries — one unauthenticated GET, and
213
+ * the endpoint is silently cut off. Confirmed this way, only the topic's owner
214
+ * can unsubscribe it. All it takes of the caller's credentials is
215
+ * `sns:ConfirmSubscription` on this one topic.
216
+ */
217
+ export declare function confirmSubscription(connection: SNSConnection, message: SnsHttpMessage): Promise<string | undefined>;
218
+ /**
219
+ * A pushed notification as the Lambda event SNS would have invoked a function
220
+ * with, so it can be handed to the same adaptor.
221
+ */
222
+ export declare function toSnsEvent(message: SnsHttpMessage, subscriptionArn?: string): {
223
+ Records: {
224
+ EventSource: string;
225
+ EventVersion: string;
226
+ EventSubscriptionArn: string;
227
+ Sns: {
228
+ Type: "Notification" | "SubscriptionConfirmation" | "UnsubscribeConfirmation";
229
+ MessageId: string;
230
+ TopicArn: string;
231
+ Subject: string | null;
232
+ Message: string;
233
+ Timestamp: string;
234
+ SignatureVersion: string;
235
+ Signature: string;
236
+ SigningCertUrl: string;
237
+ UnsubscribeUrl: string;
238
+ MessageAttributes: Record<string, {
239
+ Type: string;
240
+ Value: string;
241
+ }>;
242
+ };
243
+ }[];
244
+ };
245
+ export declare class SnsCertificateUntrusted extends Error {
246
+ readonly url: string;
247
+ constructor(url: string);
248
+ }
249
+ export declare class SnsCertificateUnavailable extends Error {
250
+ readonly url: string;
251
+ readonly status: number;
252
+ constructor(url: string, status: number);
253
+ }
254
+ export declare class SnsSignatureVersionUnknown extends Error {
255
+ readonly version: string;
256
+ constructor(version: string);
257
+ }
258
+ export declare class SnsSignatureInvalid extends Error {
259
+ readonly messageId: string;
260
+ readonly topicArn: string;
261
+ constructor(messageId: string, topicArn: string);
262
+ }
263
+ export declare class SnsMessageTypeUnknown extends Error {
264
+ readonly type: string;
265
+ constructor(type: string);
266
+ }
267
+ export declare class SnsNotAConfirmation extends Error {
268
+ readonly type: string;
269
+ constructor(type: string);
270
+ }
271
+ export declare class SnsConfirmationFailed extends Error {
272
+ readonly topicArn: string;
273
+ readonly status: number;
274
+ constructor(topicArn: string, status: number);
275
+ }
276
+ export declare class SnsEndpointNotHttp extends Error {
277
+ readonly endpoint: string;
278
+ constructor(endpoint: string);
279
+ }
280
+ export declare class SnsSubscriptionArnMissing extends Error {
281
+ readonly topicArn: string;
282
+ readonly endpoint: string;
283
+ constructor(topicArn: string, endpoint: string);
284
+ }
285
+ //#endregion
39
286
  //#region src/sns/SNSPublisher.d.ts
40
287
  type SNSPublisherOptions = {};
41
288
  export declare class SNSPublisher<TMessage extends PublishableMessage<string, any>> implements EventPublisher<TMessage> {
@@ -99,6 +346,14 @@ export declare class SNSSubscriber<TMessage extends PublishableMessage<string, a
99
346
  private setQueuePolicy;
100
347
  private subscribeToTopic;
101
348
  }
349
+ /**
350
+ * A subscriber asked to use a queue it may not create. The SQS queue behind an
351
+ * SNS subscription has to exist first, or `createQueue` has to allow it.
352
+ */
353
+ export declare class SnsQueueMissing extends Error {
354
+ readonly queueName: string | undefined;
355
+ constructor(queueName: string | undefined);
356
+ }
102
357
  //#endregion
103
- export { type SNSConnectionConfig, type SNSPublisherOptions, type SNSSubscriberOptions, type SnsAddress, snsUrl_d_exports as snsUrl };
358
+ export { type HttpSubscriptionFilter, type HttpSubscriptionSpec, type ReconcileHttpSubscriptionsOptions, type ReconciledHttpSubscriptions, type SNSConnectionConfig, type SNSPublisherOptions, type SNSSubscriberOptions, type SnsAddress, type SnsFilterPolicyScope, type SnsHttpMessage, type SubscribeHttpEndpointOptions, type VerifySnsMessageOptions, snsUrl_d_exports as snsUrl };
104
359
  //# sourceMappingURL=index.d.cts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.cts","names":[],"sources":["../../src/sns/SNSConnection.ts","../../src/sns/SNSPublisher.ts","../../src/sns/SNSSubscriber.ts"],"mappings":";;;;UAKiB;EAChB;EACA;EACA;EACA;IACC;IACA;IACA;;;qBAIW,yBAAyB;WAC5B,OAAI,mBAAA;UACL;UACA;UACA;EAEI,YAAA,QAAQ;;;;;SAgBP,qBACZ,2BACE,QAAQ;EA8BL,WAAW;EAKX,SAAS;EAKf;;;;MAOI,aAAa;;;;MAOb;;;;KC1FO;qBAEC,aAAa,iBAAiB,4CAC/B,eAAe;UAGjB;EAAA,YAAA,YAAY,eACpB,WAAU;;;;;SAOE,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,aAAa;EAQ5C,QAAQ,UAAU,aAAa;UAWvB;EAkBR,SAAS;;;;UC5CC;EAChB;EACA;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;qBAoBY,cAAc,iBAAiB,4CAChC,gBAAgB;UAUlB;UARD;UACA;UACA;UACA;UACA;UACA;EAGC,YAAA,YAAY,eACpB,UAAS;;;;;SAwBG,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,cAAc;EAoB7C,UACL,UAAU,oBACV,WAAW,SAAS,aAAa,gBAC/B;;;;EA2BG,QAAQ;UA6BA;UAwBA;UA4BA"}
1
+ {"version":3,"file":"index.d.cts","names":[],"sources":["../../src/sns/driver.ts","../../src/sns/SNSConnection.ts","../../src/sns/push.ts","../../src/sns/SNSPublisher.ts","../../src/sns/SNSSubscriber.ts"],"mappings":";;;;;;;;;qBAWa,iBAAiB;;;UCNb;EAChB;EACA;EACA;;;;;EAKA,cAAc;;qBAGF,yBAAyB;WAC5B,OAAI,mBAAA;UACL;UACA;UACA;EAER,YAAY,QAAQ;;;;;SAgBP,qBACZ,2BACE,QAAQ;EA8BL,WAAW;EAKX,SAAS;EAKf;;;;MAOI,aAAa;;;;MAOb;;;;;;;;;;;;;;;;;UCpEY;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;EAEA;;EAEA;EACA,oBAAoB;IAAiB;IAAc;;;UAwCnC;;;;;EAKhB,oBAAoB,gBAAgB;;;wBAwBrB,gBAAgB,SAAS;;;;;;;wBAgBnB,iBACrB,SAAS,gBACT,UAAS,0BACP;;;;;wBAsCmB,uBACrB,SAAS,gBACT,WAAU,gBAAgB;EAAU;EAAa;KAC/C;;KAYS;;UAGK;;;;;;;;;;;;EAYhB;;;;;;EAMA,eAAe;;EAEf,oBAAoB;;;;;;EAMpB;;UAGgB,qCAAqC;;EAErD;;;;;;;;;;;;;;;;;;wBAsEqB,sBACrB,YAAY,eACZ,SAAS,+BACP;;UAiCc,6BAA6B;;EAE7C;;EAEA;;UAGgB;;EAEhB,oBAAoB;;;;;;;EAOpB;;UAGgB;;EAEhB,eAAe;;EAEf;;EAEA;;;;;;;;;;;;;;;;;;;;;;;wBAwBqB,2BACrB,YAAY,eACZ,SAAS,oCACP,QAAQ;;;;;;;;;;;;wBAyEW,oBACrB,YAAY,eACZ,SAAS,iBACP;;;;;wBAkDa,WAAW,SAAS,gBAAgB;;;;;;MAQ/C;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MAEA;MACA;MACA,mBAAiB;QA9dsB;QAAe;;;;;qBAqe9C,gCAAgC;WACvB;EAArB,YAAqB;;qBAUT,kCAAkC;WAEpC;WACA;EAFV,YACU,aACA;;qBAUE,mCAAmC;WAC1B;EAArB,YAAqB;;qBAST,4BAA4B;WAE9B;WACA;EAFV,YACU,mBACA;;qBAWE,8BAA8B;WACrB;EAArB,YAAqB;;qBAST,4BAA4B;WACnB;EAArB,YAAqB;;qBAST,8BAA8B;WAEhC;WACA;EAFV,YACU,kBACA;;qBAWE,2BAA2B;WAClB;EAArB,YAAqB;;qBAST,kCAAkC;WAEpC;WACA;EAFV,YACU,kBACA;;;;KCzmBC;qBAEC,aAAa,iBAAiB,4CAC/B,eAAe;UAGjB;EADT,YACS,YAAY,eACpB,WAAU;;;;;SAOE,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,aAAa;EAQ5C,QAAQ,UAAU,aAAa;UAqBvB;EAwBR,SAAS;;;;UC7DC;EAChB;EACA;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;qBAoBY,cAAc,iBAAiB,4CAChC,gBAAgB;UAUlB;UARD;UACA;UACA;UACA;UACA;UACA;EAER,YACS,YAAY,eACpB,UAAS;;;;;SAwBG,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,cAAc;EAoB7C,UACL,UAAU,oBACV,WAAW,SAAS,aAAa,gBAC/B;;;;EA2BG,QAAQ;UA6BA;UAwBA;UA4BA;;;;;;qBAgBF,wBAAwB;WACf;EAArB,YAAqB"}
@@ -1,16 +1,24 @@
1
- import { i as EventSubscriber, n as EventPublisher, r as EventPublisherType, s as PublishableMessage, t as EventConnection } from "../types-lnM-qoe_.mjs";
1
+ import { d as EventPublisher, f as EventPublisherType, g as PublishableMessage, p as EventSubscriber, t as EventsDriver, u as EventConnection } from "../registry-DIx25Q5s.mjs";
2
2
  import { SnsAddress, t as snsUrl_d_exports } from "./snsUrl.mjs";
3
- import { SNSClient } from "@aws-sdk/client-sns";
3
+ import { SNSClient, SNSClientConfig } from "@aws-sdk/client-sns";
4
+ //#region src/sns/driver.d.ts
5
+ /**
6
+ * `sns://` — an SNS topic, consumed through an SQS queue subscribed to it.
7
+ * Register it with `registerEventsDriver(snsEventsDriver)`; an AWS entry
8
+ * registers `sqsEventsDriver` beside it.
9
+ */
10
+ export declare const snsEventsDriver: EventsDriver;
11
+ //#endregion
4
12
  //#region src/sns/SNSConnection.d.ts
5
13
  interface SNSConnectionConfig {
6
14
  topicArn: string;
7
15
  region?: string;
8
16
  endpoint?: string;
9
- credentials?: {
10
- accessKeyId: string;
11
- secretAccessKey: string;
12
- sessionToken?: string;
13
- };
17
+ /**
18
+ * Static keys, or a provider the SDK resolves them through — a deploy's
19
+ * profile or chain, where nothing pins a key pair.
20
+ */
21
+ credentials?: SNSClientConfig['credentials'];
14
22
  }
15
23
  export declare class SNSConnection implements EventConnection {
16
24
  readonly type = EventPublisherType.SNS;
@@ -36,6 +44,245 @@ export declare class SNSConnection implements EventConnection {
36
44
  get topicArn(): string;
37
45
  }
38
46
  //#endregion
47
+ //#region src/sns/push.d.ts
48
+ /**
49
+ * SNS delivering to an HTTP(S) endpoint, rather than to a queue that is polled.
50
+ *
51
+ * SNS POSTs each message to the subscribed URL as JSON. That is the whole
52
+ * transport: no queue in between, no poller, and the endpoint is handed the
53
+ * same envelope a Lambda subscription receives inside `Records[].Sns` — so the
54
+ * handler that runs deployed can be the one that runs here.
55
+ *
56
+ * The endpoint is public, so a message is trusted only once its signature
57
+ * checks out against a certificate SNS itself serves. Anything else that POSTs
58
+ * there is somebody's guess at the shape.
59
+ */
60
+ /** A message SNS POSTs to a subscribed HTTP endpoint. */
61
+ interface SnsHttpMessage {
62
+ Type: 'Notification' | 'SubscriptionConfirmation' | 'UnsubscribeConfirmation';
63
+ MessageId: string;
64
+ TopicArn: string;
65
+ Message: string;
66
+ Timestamp: string;
67
+ SignatureVersion: string;
68
+ Signature: string;
69
+ SigningCertURL: string;
70
+ Subject?: string;
71
+ /** Confirmation messages only. */
72
+ Token?: string;
73
+ /** Confirmation messages only: GET it to confirm. */
74
+ SubscribeURL?: string;
75
+ /** Notifications only. */
76
+ UnsubscribeURL?: string;
77
+ MessageAttributes?: Record<string, {
78
+ Type: string;
79
+ Value: string;
80
+ }>;
81
+ }
82
+ interface VerifySnsMessageOptions {
83
+ /**
84
+ * Fetch the PEM at a certificate URL. `fetch` by default; replaceable so a
85
+ * test signs with its own key instead of SNS's.
86
+ */
87
+ fetchCertificate?: (url: string) => Promise<string>;
88
+ }
89
+ /** The string SNS signed for this message. */
90
+ export declare function snsStringToSign(message: SnsHttpMessage): string;
91
+ /**
92
+ * Check that SNS sent this message: the certificate is SNS's own, and the
93
+ * signature over the message's signed fields verifies against it.
94
+ *
95
+ * Throws rather than returning false, so a caller cannot forget to look.
96
+ */
97
+ export declare function verifySnsMessage(message: SnsHttpMessage, options?: VerifySnsMessageOptions): Promise<void>;
98
+ /**
99
+ * Confirm a subscription by visiting the URL SNS sent. Until this happens SNS
100
+ * delivers nothing to the endpoint.
101
+ */
102
+ export declare function confirmSnsSubscription(message: SnsHttpMessage, request?: (url: string) => Promise<{
103
+ ok: boolean;
104
+ status: number;
105
+ }>): Promise<void>;
106
+ /** Where a subscription's filter policy is matched. */
107
+ type SnsFilterPolicyScope = 'MessageAttributes' | 'MessageBody';
108
+ /** What an HTTP subscription is created or brought up to date with. */
109
+ interface HttpSubscriptionFilter {
110
+ /**
111
+ * The event types this endpoint takes. Becomes the subscription's filter
112
+ * policy on the `type` attribute `SNSPublisher` sets, so SNS sends nothing
113
+ * else — fan-out to every subscriber, each seeing only what it named.
114
+ *
115
+ * Absent, with no {@link filterPolicy} either, for a topic whose
116
+ * publisher sets no `type` — a bucket's — whose subscriber filters what it
117
+ * is sent.
118
+ *
119
+ * Ignored when {@link filterPolicy} is given.
120
+ */
121
+ events?: readonly string[];
122
+ /**
123
+ * A filter policy of the caller's own, for messages SNS did not receive
124
+ * from `SNSPublisher` — a bucket's notifications carry no `type` attribute,
125
+ * so they are matched on their body instead.
126
+ */
127
+ filterPolicy?: Record<string, unknown>;
128
+ /** Where {@link filterPolicy} is matched. `MessageAttributes` by default. */
129
+ filterPolicyScope?: SnsFilterPolicyScope;
130
+ /**
131
+ * An SQS queue's ARN for what SNS gives up delivering. SNS retries an HTTP
132
+ * endpoint for a limited time and then drops the message, so without one an
133
+ * outage longer than that loses events.
134
+ */
135
+ deadLetterQueueArn?: string;
136
+ }
137
+ interface SubscribeHttpEndpointOptions extends HttpSubscriptionFilter {
138
+ /** The URL SNS POSTs to — `http:` or `https:`, which picks the protocol. */
139
+ endpoint: string;
140
+ }
141
+ /**
142
+ * Subscribe an HTTP endpoint to the connection's topic, converging on one
143
+ * confirmed subscription with the filter asked for — so it is safe on every
144
+ * start. What a server does against an emulator, where nothing deploys it;
145
+ * against SNS itself the deploy owns the subscription
146
+ * ({@link reconcileHttpSubscriptions}).
147
+ *
148
+ * - **none yet** — subscribed; SNS sends a confirmation to the endpoint.
149
+ * - **confirmed** — its filter and dead-letter queue are brought up to date.
150
+ * Subscribing again with different attributes is an error on SNS, and the
151
+ * events a subscriber names change.
152
+ * - **stuck pending** — a confirmation that never landed (the endpoint was
153
+ * down, or answered wrong). Subscribing the same endpoint again is a no-op
154
+ * on an emulator, so it is dropped and subscribed afresh, which sends a new
155
+ * confirmation.
156
+ */
157
+ export declare function subscribeHttpEndpoint(connection: SNSConnection, options: SubscribeHttpEndpointOptions): Promise<string | undefined>;
158
+ /** One endpoint the deploy wants subscribed, under the name it is recorded by. */
159
+ interface HttpSubscriptionSpec extends HttpSubscriptionFilter {
160
+ /** What the ARN is recorded under — the subscriber's export. */
161
+ name: string;
162
+ /** The URL SNS POSTs to. */
163
+ endpoint: string;
164
+ }
165
+ interface ReconcileHttpSubscriptionsOptions {
166
+ /** Every endpoint that should be subscribed to the topic. */
167
+ endpoints: readonly HttpSubscriptionSpec[];
168
+ /**
169
+ * The host these endpoints answer on. A subscription to an endpoint on it
170
+ * that is not in {@link endpoints} — a subscriber renamed or removed — is
171
+ * unsubscribed; anything subscribed on another host is somebody else's and
172
+ * left alone.
173
+ */
174
+ ownedHost: string;
175
+ }
176
+ interface ReconciledHttpSubscriptions {
177
+ /** Each endpoint's subscription ARN, by its name — stable across runs. */
178
+ subscriptions: Record<string, string>;
179
+ /** The names whose subscription SNS still waits to have confirmed. */
180
+ pending: string[];
181
+ /** The ARNs of what was unsubscribed as no longer wanted. */
182
+ removed: string[];
183
+ }
184
+ /**
185
+ * Converge a topic's HTTP subscriptions on the endpoints a deploy wants, and
186
+ * answer each one's ARN for the deploy to record and hand to the server.
187
+ *
188
+ * The deploy's half of push delivery against SNS itself: the server never
189
+ * subscribes, so its credentials need no `sns:Subscribe` — and the only
190
+ * subscriptions to the topic are ones the deploy made.
191
+ *
192
+ * Run it twice: once before the server starts, for the ARNs it is configured
193
+ * with — SNS answers one even while the subscription waits to be confirmed —
194
+ * and once the server is up, which subscribes each still-pending endpoint
195
+ * again so SNS resends its confirmation to a server now there to answer it.
196
+ * The ARN does not change between the two.
197
+ *
198
+ * - **absent** — subscribed with its filter.
199
+ * - **present** — its filter and dead-letter queue are brought up to date;
200
+ * pending, it is subscribed again to resend the confirmation.
201
+ * - **stale** — on {@link ReconcileHttpSubscriptionsOptions.ownedHost} and no
202
+ * longer wanted: unsubscribed. (A stale one SNS still lists as pending has
203
+ * no ARN to act on; SNS drops it unconfirmed after three days.)
204
+ */
205
+ export declare function reconcileHttpSubscriptions(connection: SNSConnection, options: ReconcileHttpSubscriptionsOptions): Promise<ReconciledHttpSubscriptions>;
206
+ /**
207
+ * Confirm a subscription through the API, as its topic's owner, rather than by
208
+ * visiting the URL SNS sent.
209
+ *
210
+ * `AuthenticateOnUnsubscribe` is the point of it. A subscription confirmed by
211
+ * visiting `SubscribeURL` can be removed by anyone holding the
212
+ * `UnsubscribeURL` every notification carries — one unauthenticated GET, and
213
+ * the endpoint is silently cut off. Confirmed this way, only the topic's owner
214
+ * can unsubscribe it. All it takes of the caller's credentials is
215
+ * `sns:ConfirmSubscription` on this one topic.
216
+ */
217
+ export declare function confirmSubscription(connection: SNSConnection, message: SnsHttpMessage): Promise<string | undefined>;
218
+ /**
219
+ * A pushed notification as the Lambda event SNS would have invoked a function
220
+ * with, so it can be handed to the same adaptor.
221
+ */
222
+ export declare function toSnsEvent(message: SnsHttpMessage, subscriptionArn?: string): {
223
+ Records: {
224
+ EventSource: string;
225
+ EventVersion: string;
226
+ EventSubscriptionArn: string;
227
+ Sns: {
228
+ Type: "Notification" | "SubscriptionConfirmation" | "UnsubscribeConfirmation";
229
+ MessageId: string;
230
+ TopicArn: string;
231
+ Subject: string | null;
232
+ Message: string;
233
+ Timestamp: string;
234
+ SignatureVersion: string;
235
+ Signature: string;
236
+ SigningCertUrl: string;
237
+ UnsubscribeUrl: string;
238
+ MessageAttributes: Record<string, {
239
+ Type: string;
240
+ Value: string;
241
+ }>;
242
+ };
243
+ }[];
244
+ };
245
+ export declare class SnsCertificateUntrusted extends Error {
246
+ readonly url: string;
247
+ constructor(url: string);
248
+ }
249
+ export declare class SnsCertificateUnavailable extends Error {
250
+ readonly url: string;
251
+ readonly status: number;
252
+ constructor(url: string, status: number);
253
+ }
254
+ export declare class SnsSignatureVersionUnknown extends Error {
255
+ readonly version: string;
256
+ constructor(version: string);
257
+ }
258
+ export declare class SnsSignatureInvalid extends Error {
259
+ readonly messageId: string;
260
+ readonly topicArn: string;
261
+ constructor(messageId: string, topicArn: string);
262
+ }
263
+ export declare class SnsMessageTypeUnknown extends Error {
264
+ readonly type: string;
265
+ constructor(type: string);
266
+ }
267
+ export declare class SnsNotAConfirmation extends Error {
268
+ readonly type: string;
269
+ constructor(type: string);
270
+ }
271
+ export declare class SnsConfirmationFailed extends Error {
272
+ readonly topicArn: string;
273
+ readonly status: number;
274
+ constructor(topicArn: string, status: number);
275
+ }
276
+ export declare class SnsEndpointNotHttp extends Error {
277
+ readonly endpoint: string;
278
+ constructor(endpoint: string);
279
+ }
280
+ export declare class SnsSubscriptionArnMissing extends Error {
281
+ readonly topicArn: string;
282
+ readonly endpoint: string;
283
+ constructor(topicArn: string, endpoint: string);
284
+ }
285
+ //#endregion
39
286
  //#region src/sns/SNSPublisher.d.ts
40
287
  type SNSPublisherOptions = {};
41
288
  export declare class SNSPublisher<TMessage extends PublishableMessage<string, any>> implements EventPublisher<TMessage> {
@@ -99,6 +346,14 @@ export declare class SNSSubscriber<TMessage extends PublishableMessage<string, a
99
346
  private setQueuePolicy;
100
347
  private subscribeToTopic;
101
348
  }
349
+ /**
350
+ * A subscriber asked to use a queue it may not create. The SQS queue behind an
351
+ * SNS subscription has to exist first, or `createQueue` has to allow it.
352
+ */
353
+ export declare class SnsQueueMissing extends Error {
354
+ readonly queueName: string | undefined;
355
+ constructor(queueName: string | undefined);
356
+ }
102
357
  //#endregion
103
- export { type SNSConnectionConfig, type SNSPublisherOptions, type SNSSubscriberOptions, type SnsAddress, snsUrl_d_exports as snsUrl };
358
+ export { type HttpSubscriptionFilter, type HttpSubscriptionSpec, type ReconcileHttpSubscriptionsOptions, type ReconciledHttpSubscriptions, type SNSConnectionConfig, type SNSPublisherOptions, type SNSSubscriberOptions, type SnsAddress, type SnsFilterPolicyScope, type SnsHttpMessage, type SubscribeHttpEndpointOptions, type VerifySnsMessageOptions, snsUrl_d_exports as snsUrl };
104
359
  //# sourceMappingURL=index.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.mts","names":[],"sources":["../../src/sns/SNSConnection.ts","../../src/sns/SNSPublisher.ts","../../src/sns/SNSSubscriber.ts"],"mappings":";;;;UAKiB;EAChB;EACA;EACA;EACA;IACC;IACA;IACA;;;qBAIW,yBAAyB;WAC5B,OAAI,mBAAA;UACL;UACA;UACA;EAEI,YAAA,QAAQ;;;;;SAgBP,qBACZ,2BACE,QAAQ;EA8BL,WAAW;EAKX,SAAS;EAKf;;;;MAOI,aAAa;;;;MAOb;;;;KC1FO;qBAEC,aAAa,iBAAiB,4CAC/B,eAAe;UAGjB;EAAA,YAAA,YAAY,eACpB,WAAU;;;;;SAOE,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,aAAa;EAQ5C,QAAQ,UAAU,aAAa;UAWvB;EAkBR,SAAS;;;;UC5CC;EAChB;EACA;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;qBAoBY,cAAc,iBAAiB,4CAChC,gBAAgB;UAUlB;UARD;UACA;UACA;UACA;UACA;UACA;EAGC,YAAA,YAAY,eACpB,UAAS;;;;;SAwBG,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,cAAc;EAoB7C,UACL,UAAU,oBACV,WAAW,SAAS,aAAa,gBAC/B;;;;EA2BG,QAAQ;UA6BA;UAwBA;UA4BA"}
1
+ {"version":3,"file":"index.d.mts","names":[],"sources":["../../src/sns/driver.ts","../../src/sns/SNSConnection.ts","../../src/sns/push.ts","../../src/sns/SNSPublisher.ts","../../src/sns/SNSSubscriber.ts"],"mappings":";;;;;;;;;qBAWa,iBAAiB;;;UCNb;EAChB;EACA;EACA;;;;;EAKA,cAAc;;qBAGF,yBAAyB;WAC5B,OAAI,mBAAA;UACL;UACA;UACA;EAER,YAAY,QAAQ;;;;;SAgBP,qBACZ,2BACE,QAAQ;EA8BL,WAAW;EAKX,SAAS;EAKf;;;;MAOI,aAAa;;;;MAOb;;;;;;;;;;;;;;;;;UCpEY;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;EAEA;;EAEA;EACA,oBAAoB;IAAiB;IAAc;;;UAwCnC;;;;;EAKhB,oBAAoB,gBAAgB;;;wBAwBrB,gBAAgB,SAAS;;;;;;;wBAgBnB,iBACrB,SAAS,gBACT,UAAS,0BACP;;;;;wBAsCmB,uBACrB,SAAS,gBACT,WAAU,gBAAgB;EAAU;EAAa;KAC/C;;KAYS;;UAGK;;;;;;;;;;;;EAYhB;;;;;;EAMA,eAAe;;EAEf,oBAAoB;;;;;;EAMpB;;UAGgB,qCAAqC;;EAErD;;;;;;;;;;;;;;;;;;wBAsEqB,sBACrB,YAAY,eACZ,SAAS,+BACP;;UAiCc,6BAA6B;;EAE7C;;EAEA;;UAGgB;;EAEhB,oBAAoB;;;;;;;EAOpB;;UAGgB;;EAEhB,eAAe;;EAEf;;EAEA;;;;;;;;;;;;;;;;;;;;;;;wBAwBqB,2BACrB,YAAY,eACZ,SAAS,oCACP,QAAQ;;;;;;;;;;;;wBAyEW,oBACrB,YAAY,eACZ,SAAS,iBACP;;;;;wBAkDa,WAAW,SAAS,gBAAgB;;;;;;MAQ/C;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MAEA;MACA;MACA,mBAAiB;QA9dsB;QAAe;;;;;qBAqe9C,gCAAgC;WACvB;EAArB,YAAqB;;qBAUT,kCAAkC;WAEpC;WACA;EAFV,YACU,aACA;;qBAUE,mCAAmC;WAC1B;EAArB,YAAqB;;qBAST,4BAA4B;WAE9B;WACA;EAFV,YACU,mBACA;;qBAWE,8BAA8B;WACrB;EAArB,YAAqB;;qBAST,4BAA4B;WACnB;EAArB,YAAqB;;qBAST,8BAA8B;WAEhC;WACA;EAFV,YACU,kBACA;;qBAWE,2BAA2B;WAClB;EAArB,YAAqB;;qBAST,kCAAkC;WAEpC;WACA;EAFV,YACU,kBACA;;;;KCzmBC;qBAEC,aAAa,iBAAiB,4CAC/B,eAAe;UAGjB;EADT,YACS,YAAY,eACpB,WAAU;;;;;SAOE,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,aAAa;EAQ5C,QAAQ,UAAU,aAAa;UAqBvB;EAwBR,SAAS;;;;UC7DC;EAChB;EACA;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;qBAoBY,cAAc,iBAAiB,4CAChC,gBAAgB;UAUlB;UARD;UACA;UACA;UACA;UACA;UACA;EAER,YACS,YAAY,eACpB,UAAS;;;;;SAwBG,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,cAAc;EAoB7C,UACL,UAAU,oBACV,WAAW,SAAS,aAAa,gBAC/B;;;;EA2BG,QAAQ;UA6BA;UAwBA;UA4BA;;;;;;qBAgBF,wBAAwB;WACf;EAArB,YAAqB"}