@forklaunch/core 2.1.1 → 3.0.0

package/lib/http/emailClient.d.ts

@@ -0,0 +1,102 @@
+import { InstanceGatewayRequestError } from './instanceGateway';
+/**
+ * Client for platform-held email, used from inside a managed instance.
+ *
+ * The instance never holds a mail credential. It signs each request with its
+ * own HMAC key; the platform sends through Amazon SES from the instance's own
+ * sending identity (`no-reply@<instance>.<platform sending domain>`, a claimed
+ * custom domain later) under a per-instance configuration set, enforces the
+ * product's daily quota and rate, and refuses addresses on the instance's
+ * suppression list (hard bounces and complaints).
+ *
+ * Delivery outcomes come back as platform events on
+ * `/platform-events/email`: `email.delivered`, `email.bounced` and
+ * `email.complained`, each carrying the `messageId` `send` returned. A bounced
+ * or complained address is suppressed by the platform; mark it undeliverable
+ * in the app too so the person can be asked for a new one.
+ *
+ * Locally, `forklaunch infra add <service> email` points the service at the
+ * gateway mock in docker-compose (PLATFORM_GATEWAY_URL, INSTANCE_ID,
+ * INSTANCE_HMAC_KEY), which records messages (GET /__mock/email/messages) and
+ * emits the same events. Outside managed mode and without those settings,
+ * `createEmailClient` refuses to be created.
+ *
+ * What to put where: the body may hold what the recipient is entitled to
+ * read; the subject shows on lock screens, in notification previews and in
+ * mail logs, so never put protected data (a `.deanon` value) in it.
+ *
+ * @example
+ * const email = createEmailClient();
+ * const { messageId } = await email.send({
+ *   to: 'pat@example.com',
+ *   subject: 'Your appointment is confirmed',
+ *   text: 'See you on Tuesday at 10:00.'
+ * });
+ * if (await email.suppressed('pat@example.com')) { … ask for another address }
+ */
+export interface EmailClientOptions {
+    /** Platform base URL. Default: `PLATFORM_GATEWAY_URL`. */
+    gatewayUrl?: string;
+    /** This instance's id. Default: `INSTANCE_ID`. */
+    instanceId?: string;
+    /** This instance's HMAC key. Default: `INSTANCE_HMAC_KEY`. */
+    hmacKey?: string;
+    fetch?: typeof fetch;
+}
+export interface EmailSendRequest {
+    /** One address or up to 50. */
+    to: string | string[];
+    /** Plain text, one line; shown in previews and logs — no protected data. */
+    subject: string;
+    /** At least one of `text` and `html`. */
+    text?: string;
+    html?: string;
+    replyTo?: string | string[];
+    /**
+     * Up to 10 tags, echoed on the delivery events. Names and values:
+     * letters, digits, `_` and `-`. Names starting `fl-` or `ses:` are reserved.
+     */
+    tags?: Record<string, string>;
+}
+export interface EmailSendResult {
+    /** The provider's message id; delivery events carry it. */
+    messageId: string;
+}
+/** Data on `email.delivered`, `email.bounced` and `email.complained` events. */
+export interface EmailEventData {
+    messageId: string;
+    recipients: string[];
+    tags?: Record<string, string>;
+    /** `email.bounced`: `Permanent`, `Transient` or `Undetermined`. */
+    bounceType?: string;
+    bounceSubType?: string;
+    /** `email.bounced`: whether the platform suppressed the addresses. */
+    permanent?: boolean;
+    /** `email.complained`: the feedback type the mailbox provider reported. */
+    feedbackType?: string;
+}
+/** A refusal or failure, from the gateway or from validation before sending. */
+export declare class EmailRequestError extends InstanceGatewayRequestError {
+    readonly name: 'EmailRequestError';
+}
+export interface EmailClient {
+    /** Send one message; throws `EmailRequestError` on a refusal. */
+    send(request: EmailSendRequest): Promise<EmailSendResult>;
+    /** Whether the platform refuses to send to `address` (bounce/complaint). */
+    suppressed(address: string): Promise<boolean>;
+}
+/** Limits the platform enforces too; checked here so a bad call fails fast. */
+export declare const EMAIL_LIMITS: {
+    readonly maxRecipients: 50;
+    readonly maxAddressLength: 254;
+    readonly maxSubjectLength: 998;
+    /** text + html, UTF-8 bytes. */
+    readonly maxBodyBytes: number;
+    readonly maxTags: 10;
+};
+/** Whether `address` is a plain mailbox address (`local@domain.tld`). */
+export declare function isEmailAddress(address: unknown): address is string;
+/** Validate a send request the way the gateway does; returns the wire body. */
+export declare function validateEmailSendRequest(request: EmailSendRequest): Record<string, unknown>;
+export declare function createEmailClient(options?: EmailClientOptions): EmailClient;
+//# sourceMappingURL=emailClient.d.ts.map

package/lib/http/emailClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emailClient.d.ts","sourceRoot":"","sources":["../../src/http/emailClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,2BAA2B,EAE5B,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,gFAAgF;AAChF,qBAAa,iBAAkB,SAAQ,2BAA2B;IAChE,SAAkB,IAAI,EAAG,mBAAmB,CAAU;CACvD;AAED,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC1D,4EAA4E;IAC5E,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/C;AAED,+EAA+E;AAC/E,eAAO,MAAM,YAAY;aACvB,aAAa,EAAE,EAAE;aACjB,gBAAgB,EAAE,GAAG;aACrB,gBAAgB,EAAE,GAAG;IACrB,gCAAgC;aAChC,YAAY;aACZ,OAAO,EAAE,EAAE;CACH,CAAC;AAMX,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,MAAM,CAMlE;AAyBD,+EAA+E;AAC/E,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,gBAAgB,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyCzB;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,kBAAuB,GAC/B,WAAW,CAuDb"}

package/lib/http/index.d.ts

@@ -4,6 +4,13 @@ export * from './cluster/cluster.types';
 export * from './cluster/isPortBound';
 export * from './createHmacToken';
 export * from './generateHmacAuthHeaders';
+export * from './instanceGateway';
+export * from './modelGatewayClient';
+export * from './emailClient';
+export * from './smsClient';
+export * from './whatsappClient';
+export * from './voiceClient';
+export * from './paymentsClient';
 export * from './discriminateAuthMethod';
 export * from './guards/isForklaunchRequest';
 export * from './guards/isForklaunchRouter';

package/lib/http/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/http/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC;AACnC,cAAc,sCAAsC,CAAC;AACrD,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0CAA0C,CAAC;AACzD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+CAA+C,CAAC;AAC9D,cAAc,wDAAwD,CAAC;AACvE,cAAc,yCAAyC,CAAC;AACxD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sCAAsC,CAAC;AACrD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,oCAAoC,CAAC;AACnD,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iCAAiC,CAAC;AAChD,cAAc,sCAAsC,CAAC;AACrD,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/http/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC;AACnC,cAAc,sCAAsC,CAAC;AACrD,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0CAA0C,CAAC;AACzD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+CAA+C,CAAC;AAC9D,cAAc,wDAAwD,CAAC;AACvE,cAAc,yCAAyC,CAAC;AACxD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sCAAsC,CAAC;AACrD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,oCAAoC,CAAC;AACnD,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iCAAiC,CAAC;AAChD,cAAc,sCAAsC,CAAC;AACrD,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,cAAc,4BAA4B,CAAC"}