@walkeros/server-destination-aws 4.7.0-next-1790722899482 → 4.7.0

package/dist/examples/index.d.ts

@@ -5,19 +5,27 @@ import { SNSClientConfig, CreateTopicCommandInput, PublishCommandInput, GetTopic
 import { STSClientConfig, GetCallerIdentityCommandInput } from '@aws-sdk/client-sts';
 
 /**
- * The part of an AWS SDK v3 client this destination calls: `send` with a
- * command. `FirehoseClient` satisfies it, and so does an injected mock (tests,
- * simulate) without a cast.
+ * The part of an AWS SDK v3 client this package calls: `send` with a command,
+ * and `destroy` on a client it created. The SDK clients satisfy it, and so
+ * does an injected mock (tests, simulate) without a cast.
  */
-interface SendClient$1 {
+interface SendClient {
     send(command: object): Promise<unknown>;
+    destroy?(): void;
 }
+
+type FirehoseClientConstructor = new (config: FirehoseClientConfig) => SendClient;
+type PutRecordBatchCommandConstructor = new (input: PutRecordBatchCommandInput) => {
+    readonly input: PutRecordBatchCommandInput;
+};
+/**
+ * Optional SDK overrides. Each one present wins over the SDK the package
+ * imports; tests and simulate inject mocks here.
+ */
 interface Env$1 extends DestinationServer.Env {
-    AWS: {
-        FirehoseClient: new (config: FirehoseClientConfig) => SendClient$1;
-        PutRecordBatchCommand: new (input: PutRecordBatchCommandInput) => {
-            readonly input: PutRecordBatchCommandInput;
-        };
+    AWS?: {
+        FirehoseClient?: FirehoseClientConstructor;
+        PutRecordBatchCommand?: PutRecordBatchCommandConstructor;
     };
 }
 
@@ -29,50 +37,45 @@ declare namespace env$1 {
 }
 
 /**
- * Default firehose push -- client.send(new PutRecordBatchCommand({...}))
- * Records contain the full event JSON-stringified as Buffer Data.
+ * The copy-paste config: the stream, its region, and keys from `$secret`.
+ * `init` builds one client from it, offline, with a per-attempt timeout of a
+ * quarter of the collector's 10 s race, so the SDK's three attempts end
+ * before the collector stops waiting.
  */
+declare const init$1: Flow.StepExample;
 declare const firehoseRecord: Flow.StepExample;
-/**
- * Order event -- same pattern, full event serialized in Records[0].Data.
- */
 declare const orderEvent$1: Flow.StepExample;
-/**
- * User signup -- full event including user fields is serialized to Firehose.
- */
 declare const userSignupEvent: Flow.StepExample;
+declare const mappedRecord: Flow.StepExample;
 
 declare const step$1_firehoseRecord: typeof firehoseRecord;
+declare const step$1_mappedRecord: typeof mappedRecord;
 declare const step$1_userSignupEvent: typeof userSignupEvent;
 declare namespace step$1 {
-  export { step$1_firehoseRecord as firehoseRecord, orderEvent$1 as orderEvent, step$1_userSignupEvent as userSignupEvent };
+  export { step$1_firehoseRecord as firehoseRecord, init$1 as init, step$1_mappedRecord as mappedRecord, orderEvent$1 as orderEvent, step$1_userSignupEvent as userSignupEvent };
 }
 
 declare namespace index$1 {
   export { env$1 as env, step$1 as step };
 }
 
-/**
- * The part of an AWS SDK v3 client this destination calls: `send` with a
- * command. `SNSClient` and `STSClient` satisfy it, and so does an injected
- * mock (tests, simulate) without a cast.
- */
-interface SendClient {
-    send(command: object): Promise<unknown>;
-}
 /** An AWS SDK v3 command class, as far as this destination builds one. */
 type CommandConstructor<Input> = new (input: Input) => {
     readonly input: Input;
 };
+/**
+ * Optional SDK overrides. Each one present wins over the SDK the package
+ * imports; tests and simulate inject mocks here.
+ */
 interface Env extends DestinationServer.Env {
-    AWS: {
-        SNSClient: new (config: SNSClientConfig) => SendClient;
-        CreateTopicCommand: CommandConstructor<CreateTopicCommandInput>;
-        PublishCommand: CommandConstructor<PublishCommandInput>;
-        GetTopicAttributesCommand: CommandConstructor<GetTopicAttributesCommandInput>;
-        SubscribeCommand: CommandConstructor<SubscribeCommandInput>;
-        STSClient: new (config: STSClientConfig) => SendClient;
-        GetCallerIdentityCommand: CommandConstructor<GetCallerIdentityCommandInput>;
+    AWS?: {
+        SNSClient?: new (config: SNSClientConfig) => SendClient;
+        CreateTopicCommand?: CommandConstructor<CreateTopicCommandInput>;
+        PublishCommand?: CommandConstructor<PublishCommandInput>;
+        GetTopicAttributesCommand?: CommandConstructor<GetTopicAttributesCommandInput>;
+        SubscribeCommand?: CommandConstructor<SubscribeCommandInput>;
+        STSClient?: new (config: STSClientConfig) => SendClient;
+        GetCallerIdentityCommand?: CommandConstructor<GetCallerIdentityCommandInput>;
     };
 }
 
@@ -86,15 +89,24 @@ declare namespace env {
   export { env_push as push, env_simulation as simulation };
 }
 
+/**
+ * The copy-paste config: the topic ARN, which also names the region, and
+ * keys from `$secret`. `init` builds one client from it, offline; nothing is
+ * sent until the first event.
+ */
+declare const init: Flow.StepExample;
 declare const pageView: Flow.StepExample;
 declare const orderEvent: Flow.StepExample;
 declare const attributedPublish: Flow.StepExample;
+declare const mappedMessage: Flow.StepExample;
 
 declare const step_attributedPublish: typeof attributedPublish;
+declare const step_init: typeof init;
+declare const step_mappedMessage: typeof mappedMessage;
 declare const step_orderEvent: typeof orderEvent;
 declare const step_pageView: typeof pageView;
 declare namespace step {
-  export { step_attributedPublish as attributedPublish, step_orderEvent as orderEvent, step_pageView as pageView };
+  export { step_attributedPublish as attributedPublish, step_init as init, step_mappedMessage as mappedMessage, step_orderEvent as orderEvent, step_pageView as pageView };
 }
 
 declare const index_env: typeof env;

package/dist/examples/index.js

@@ -40,19 +40,27 @@ __export(env_exports, {
   push: () => push,
   simulation: () => simulation
 });
+function hasRecords(value) {
+  return typeof value === "object" && value !== null && "Records" in value && Array.isArray(value.Records);
+}
 var MockFirehoseClient = class {
   config;
   constructor(config) {
     this.config = config;
   }
-  async send(_command) {
+  async send(command) {
+    const input = "input" in command ? command.input : void 0;
+    const records = hasRecords(input) ? input.Records : [];
     return {
-      RecordId: "mock-record-id",
-      ResponseMetadata: {
-        RequestId: "mock-request-id"
-      }
+      FailedPutCount: 0,
+      Encrypted: false,
+      RequestResponses: records.map((_, index) => ({
+        RecordId: `mock-record-id-${index}`
+      }))
     };
   }
+  destroy() {
+  }
 };
 var MockPutRecordBatchCommand = class {
   input;
@@ -64,7 +72,6 @@ var MockPutRecordBatchCommand = class {
   }
 };
 var push = {
-  // Environment for push operations
   AWS: {
     FirehoseClient: MockFirehoseClient,
     PutRecordBatchCommand: MockPutRecordBatchCommand
@@ -76,110 +83,122 @@ var simulation = ["call:AWS.FirehoseClient.send"];
 var step_exports = {};
 __export(step_exports, {
   firehoseRecord: () => firehoseRecord,
+  init: () => init,
+  mappedRecord: () => mappedRecord,
   orderEvent: () => orderEvent,
   userSignupEvent: () => userSignupEvent
 });
+var import_core2 = require("@walkeros/core");
+
+// src/lib/payload.ts
 var import_core = require("@walkeros/core");
-var firehoseRecord = {
-  title: "Page view record",
-  description: "A page view is sent to Kinesis Firehose as a single record with the full event JSON-stringified into the Data buffer.",
-  in: (0, import_core.getEvent)("page view", {
-    id: "ev-1700001000",
-    timestamp: 1700001e3,
-    data: { title: "Home", url: "https://example.com/" },
-    source: { type: "express", platform: "server" }
-  }),
-  mapping: void 0,
+
+// src/firehose/lib/records.ts
+function toRecordData(payload, newline = true) {
+  const json = JSON.stringify(payload);
+  if (typeof json !== "string")
+    throw new TypeError("The payload does not serialize to JSON.");
+  return Buffer.from(newline ? `${json}
+` : json);
+}
+
+// src/firehose/examples/step.ts
+var STREAM = "walkeros-events";
+var init = {
+  title: "Initialization",
+  description: "Init builds one FirehoseClient for the stream region with the credentials from config.credentials and a 2500 ms per-attempt timeout. Nothing is sent until the first event.",
+  in: {
+    settings: { streamName: STREAM, region: "eu-central-1" },
+    credentials: {
+      accessKeyId: "$secret.AWS_ACCESS_KEY_ID",
+      secretAccessKey: "$secret.AWS_SECRET_ACCESS_KEY"
+    }
+  },
   out: [
     [
-      "client.send",
+      "new FirehoseClient",
       {
-        DeliveryStreamName: "walkeros-events",
-        Records: [
-          {
-            Data: Buffer.from(
-              JSON.stringify(
-                (0, import_core.getEvent)("page view", {
-                  id: "ev-1700001000",
-                  timestamp: 1700001e3,
-                  data: { title: "Home", url: "https://example.com/" },
-                  source: { type: "express", platform: "server" }
-                })
-              )
-            )
-          }
-        ]
+        region: "eu-central-1",
+        credentials: {
+          accessKeyId: "$secret.AWS_ACCESS_KEY_ID",
+          secretAccessKey: "$secret.AWS_SECRET_ACCESS_KEY"
+        },
+        requestHandler: { requestTimeout: 2500, throwOnRequestTimeout: true }
       }
     ]
   ]
 };
-var orderEvent = {
-  title: "Order record",
-  description: "An order complete event is serialized and delivered to Firehose as a batch record for downstream storage.",
-  in: (0, import_core.getEvent)("order complete", {
-    id: "ev-1700001001",
-    timestamp: 1700001001,
-    data: { id: "ORD-400", total: 99.99, currency: "EUR" },
-    source: { type: "express", platform: "server" }
-  }),
-  mapping: void 0,
-  out: [
+var pageEvent = (0, import_core2.getEvent)("page view", {
+  id: "ev-1700001000",
+  timestamp: 1700001e3,
+  data: { title: "Home", url: "https://example.com/" },
+  source: { type: "express", platform: "server" }
+});
+var orderEvt = (0, import_core2.getEvent)("order complete", {
+  id: "ev-1700001001",
+  timestamp: 1700001001,
+  data: { id: "ORD-400", total: 99.99, currency: "EUR" },
+  source: { type: "express", platform: "server" }
+});
+var signupEvt = (0, import_core2.getEvent)("user signup", {
+  id: "ev-1700001002",
+  timestamp: 1700001002,
+  data: { plan: "pro", source: "landing-page" },
+  user: { id: "usr-789", email: "new@example.com" },
+  source: { type: "express", platform: "server" }
+});
+function sent(payload) {
+  return [
     [
       "client.send",
       {
-        DeliveryStreamName: "walkeros-events",
-        Records: [
-          {
-            Data: Buffer.from(
-              JSON.stringify(
-                (0, import_core.getEvent)("order complete", {
-                  id: "ev-1700001001",
-                  timestamp: 1700001001,
-                  data: { id: "ORD-400", total: 99.99, currency: "EUR" },
-                  source: { type: "express", platform: "server" }
-                })
-              )
-            )
-          }
-        ]
+        DeliveryStreamName: STREAM,
+        Records: [{ Data: toRecordData(payload) }]
       }
     ]
-  ]
+  ];
+}
+var firehoseRecord = {
+  title: "Page view record",
+  description: "A page view is sent to Firehose as one record: the full event as JSON followed by a newline.",
+  in: pageEvent,
+  mapping: void 0,
+  out: sent(pageEvent)
+};
+var orderEvent = {
+  title: "Order record",
+  description: "An order complete event is serialized and delivered to Firehose as one newline-terminated record.",
+  in: orderEvt,
+  mapping: void 0,
+  out: sent(orderEvt)
 };
 var userSignupEvent = {
   title: "User signup record",
   description: "A user signup event including user fields is streamed to Firehose as a JSON record.",
-  in: (0, import_core.getEvent)("user signup", {
-    id: "ev-1700001002",
-    timestamp: 1700001002,
-    data: { plan: "pro", source: "landing-page" },
-    user: { id: "usr-789", email: "new@example.com" },
-    source: { type: "express", platform: "server" }
-  }),
+  in: signupEvt,
   mapping: void 0,
-  out: [
-    [
-      "client.send",
-      {
-        DeliveryStreamName: "walkeros-events",
-        Records: [
-          {
-            Data: Buffer.from(
-              JSON.stringify(
-                (0, import_core.getEvent)("user signup", {
-                  id: "ev-1700001002",
-                  timestamp: 1700001002,
-                  data: { plan: "pro", source: "landing-page" },
-                  user: { id: "usr-789", email: "new@example.com" },
-                  source: { type: "express", platform: "server" }
-                })
-              )
-            )
-          }
-        ]
+  out: sent(signupEvt)
+};
+var mappedRecord = {
+  title: "Mapped record",
+  description: "A mapping that produces an object sends that object as the record instead of the full event. Keep the event id in it for deduplication.",
+  in: orderEvt,
+  mapping: {
+    data: {
+      map: {
+        id: "id",
+        name: "name",
+        order_id: "data.id",
+        total: "data.total"
       }
-    ]
-  ]
+    }
+  },
+  out: sent({
+    id: "ev-1700001001",
+    name: "order complete",
+    order_id: "ORD-400",
+    total: 99.99
+  })
 };
 
 // src/sns/examples/index.ts
@@ -239,6 +258,8 @@ var MockSNSClient = class {
       return { MessageId: "mock-message-id" };
     return {};
   }
+  destroy() {
+  }
 };
 var MockSTSClient = class {
   constructor(config) {
@@ -246,7 +267,12 @@ var MockSTSClient = class {
   }
   config;
   async send() {
-    return { Account: "123456789012" };
+    return {
+      Account: "123456789012",
+      Arn: "arn:aws:iam::123456789012:user/walkeros"
+    };
+  }
+  destroy() {
   }
 };
 var push2 = {
@@ -266,24 +292,52 @@ var simulation2 = ["call:AWS.SNSClient.send"];
 var step_exports2 = {};
 __export(step_exports2, {
   attributedPublish: () => attributedPublish,
+  init: () => init2,
+  mappedMessage: () => mappedMessage,
   orderEvent: () => orderEvent2,
   pageView: () => pageView
 });
-var import_core2 = require("@walkeros/core");
-var pageEvent = (0, import_core2.getEvent)("page view", {
+var import_core3 = require("@walkeros/core");
+var TOPIC_ARN2 = "arn:aws:sns:eu-central-1:123456789012:walkeros-events";
+var FIFO_ARN = "arn:aws:sns:eu-central-1:123456789012:walkeros-events.fifo";
+var init2 = {
+  title: "Initialization",
+  description: "Init builds one SNSClient in the region of the topic ARN with the credentials from config.credentials and a 2500 ms per-attempt timeout. No topic is created and nothing is sent until the first event.",
+  in: {
+    settings: { topicArn: TOPIC_ARN2 },
+    credentials: {
+      accessKeyId: "$secret.AWS_ACCESS_KEY_ID",
+      secretAccessKey: "$secret.AWS_SECRET_ACCESS_KEY"
+    }
+  },
+  out: [
+    [
+      "new SNSClient",
+      {
+        region: "eu-central-1",
+        credentials: {
+          accessKeyId: "$secret.AWS_ACCESS_KEY_ID",
+          secretAccessKey: "$secret.AWS_SECRET_ACCESS_KEY"
+        },
+        requestHandler: { requestTimeout: 2500, throwOnRequestTimeout: true }
+      }
+    ]
+  ]
+};
+var pageEvent2 = (0, import_core3.getEvent)("page view", {
   id: "ev-1700001000",
   timestamp: 1700001e3,
   data: { title: "Home", url: "https://example.com/" },
   source: { type: "express", platform: "server" }
 });
-var orderEvt = (0, import_core2.getEvent)("order complete", {
+var orderEvt2 = (0, import_core3.getEvent)("order complete", {
   id: "ev-1700001001",
   timestamp: 1700001001,
   data: { id: "ORD-400", total: 99.99, currency: "EUR" },
   user: { id: "usr-789" },
   source: { type: "express", platform: "server" }
 });
-var productViewEvt = (0, import_core2.getEvent)("product view", {
+var productViewEvt = (0, import_core3.getEvent)("product view", {
   id: "ev-1700001002",
   timestamp: 1700001002,
   data: { id: "SKU-1", tenant_id: "acme" },
@@ -292,30 +346,31 @@ var productViewEvt = (0, import_core2.getEvent)("product view", {
 var pageView = {
   title: "Page view publish",
   description: "A page view event is JSON-stringified and published as the Message of an SNS Publish call.",
-  in: pageEvent,
+  in: pageEvent2,
   mapping: void 0,
   out: [
     [
       "client.send",
       {
-        TopicArn: "arn:aws:sns:eu-central-1:000000000000:walkeros-events",
-        Message: JSON.stringify(pageEvent)
+        TopicArn: TOPIC_ARN2,
+        Message: JSON.stringify(pageEvent2)
       }
     ]
   ]
 };
 var orderEvent2 = {
   title: "Order publish with FIFO group (path-resolved)",
-  description: 'An order complete event is published with a FIFO messageGroupId resolved from the event via the mapping path "user.id". `messageGroupId` is a `Mapping.Value`, so a string path is sufficient; no literal is hard-coded.',
-  in: orderEvt,
+  description: 'An order complete event is published to a FIFO topic with a messageGroupId resolved from the event via the mapping path "user.id". The deduplication id defaults to the event id.',
+  in: orderEvt2,
   mapping: { settings: { messageGroupId: "user.id" } },
   out: [
     [
       "client.send",
       {
-        TopicArn: "arn:aws:sns:eu-central-1:000000000000:walkeros-events.fifo",
-        Message: JSON.stringify(orderEvt),
-        MessageGroupId: "usr-789"
+        TopicArn: FIFO_ARN,
+        Message: JSON.stringify(orderEvt2),
+        MessageGroupId: "usr-789",
+        MessageDeduplicationId: "ev-1700001001"
       }
     ]
   ]
@@ -336,7 +391,7 @@ var attributedPublish = {
     [
       "client.send",
       {
-        TopicArn: "arn:aws:sns:eu-central-1:000000000000:walkeros-events",
+        TopicArn: TOPIC_ARN2,
         Message: JSON.stringify(productViewEvt),
         MessageAttributes: {
           schema_version: { DataType: "String", StringValue: "v4" },
@@ -346,6 +401,30 @@ var attributedPublish = {
     ]
   ]
 };
+var mappedMessage = {
+  title: "Mapped message",
+  description: "A mapping that produces an object publishes that object as the Message instead of the full event. Keep the event id in it for deduplication.",
+  in: orderEvt2,
+  mapping: {
+    data: {
+      map: { id: "id", name: "name", order_id: "data.id", total: "data.total" }
+    }
+  },
+  out: [
+    [
+      "client.send",
+      {
+        TopicArn: TOPIC_ARN2,
+        Message: JSON.stringify({
+          id: "ev-1700001001",
+          name: "order complete",
+          order_id: "ORD-400",
+          total: 99.99
+        })
+      }
+    ]
+  ]
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   env,