@forklaunch/implementation-messaging-twilio 1.0.0

package/lib/services/index.mjs

@@ -0,0 +1,164 @@
+// services/sms.service.ts
+import {
+  evaluateTelemetryOptions
+} from "@forklaunch/core/http";
+import { SmsStatusEnum } from "@forklaunch/implementation-messaging-base/enum";
+import { EntityManager } from "@mikro-orm/core";
+
+// domain/enum/twilioMessageStatus.enum.ts
+var TwilioMessageStatusEnum = {
+  QUEUED: "queued",
+  ACCEPTED: "accepted",
+  SCHEDULED: "scheduled",
+  CANCELED: "canceled",
+  SENDING: "sending",
+  SENT: "sent",
+  DELIVERED: "delivered",
+  UNDELIVERED: "undelivered",
+  FAILED: "failed",
+  RECEIVING: "receiving",
+  RECEIVED: "received",
+  READ: "read"
+};
+
+// services/sms.service.ts
+var mapTwilioMessageStatus = (messageStatus) => {
+  switch (messageStatus) {
+    case TwilioMessageStatusEnum.SENT:
+      return SmsStatusEnum.SENT;
+    case TwilioMessageStatusEnum.DELIVERED:
+    case TwilioMessageStatusEnum.READ:
+      return SmsStatusEnum.DELIVERED;
+    case TwilioMessageStatusEnum.UNDELIVERED:
+      return SmsStatusEnum.UNDELIVERED;
+    case TwilioMessageStatusEnum.FAILED:
+    case TwilioMessageStatusEnum.CANCELED:
+      return SmsStatusEnum.FAILED;
+    case TwilioMessageStatusEnum.QUEUED:
+    case TwilioMessageStatusEnum.ACCEPTED:
+    case TwilioMessageStatusEnum.SCHEDULED:
+    case TwilioMessageStatusEnum.SENDING:
+    default:
+      return SmsStatusEnum.QUEUED;
+  }
+};
+var TWILIO_API_BASE_URL = "https://api.twilio.com/2010-04-01";
+var TwilioSmsService = class {
+  constructor(accountSid, authToken, fromNumber, em, openTelemetryCollector, schemaValidator, mappers, options) {
+    this.options = options;
+    this.accountSid = accountSid;
+    this.authToken = authToken;
+    this.fromNumber = fromNumber;
+    this.em = em;
+    this.openTelemetryCollector = openTelemetryCollector;
+    this.schemaValidator = schemaValidator;
+    this.mappers = mappers;
+    this.evaluatedTelemetryOptions = options?.telemetry ? evaluateTelemetryOptions(options.telemetry).enabled : {
+      logging: false,
+      metrics: false,
+      tracing: false
+    };
+  }
+  options;
+  evaluatedTelemetryOptions;
+  accountSid;
+  authToken;
+  fromNumber;
+  em;
+  openTelemetryCollector;
+  schemaValidator;
+  mappers;
+  async sendSms(smsDto, em, ...args) {
+    if (this.evaluatedTelemetryOptions.logging) {
+      this.openTelemetryCollector.info("Sending sms via twilio", {
+        to: smsDto.to
+      });
+    }
+    const smsRecord = await this.mappers.SendSmsMapper.toEntity(
+      smsDto,
+      em ?? this.em,
+      ...args[0] instanceof EntityManager ? args.slice(1) : args
+    );
+    const record = smsRecord;
+    const response = await fetch(
+      `${TWILIO_API_BASE_URL}/Accounts/${this.accountSid}/Messages.json`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Basic ${Buffer.from(
+            `${this.accountSid}:${this.authToken}`
+          ).toString("base64")}`,
+          "Content-Type": "application/x-www-form-urlencoded"
+        },
+        body: new URLSearchParams({
+          To: smsDto.to,
+          From: this.fromNumber,
+          Body: smsDto.body
+        }).toString()
+      }
+    );
+    if (response.ok) {
+      const message = await response.json();
+      record.providerMessageId = message.sid;
+      record.status = mapTwilioMessageStatus(message.status);
+      record.error = message.error_message ?? null;
+    } else {
+      const errorBody = await response.text();
+      record.status = SmsStatusEnum.FAILED;
+      record.error = `Twilio API error (${response.status}): ${errorBody}`;
+      this.openTelemetryCollector.error("Twilio message dispatch failed", {
+        status: response.status,
+        error: errorBody
+      });
+    }
+    await (em ?? this.em).transactional(async (innerEm) => {
+      await innerEm.persist(smsRecord);
+    });
+    return this.mappers.SmsRecordMapper.toDto(
+      smsRecord
+    );
+  }
+  async getSmsRecord({ id }, em) {
+    if (this.evaluatedTelemetryOptions.logging) {
+      this.openTelemetryCollector.info("Getting sms record", { id });
+    }
+    const smsRecord = await (em ?? this.em).findOneOrFail(
+      this.mappers.SmsRecordMapper.entity,
+      { id }
+    );
+    return this.mappers.SmsRecordMapper.toDto(
+      smsRecord
+    );
+  }
+  /**
+   * Maps a Twilio delivery-status callback (MessageStatus, MessageSid,
+   * ErrorMessage) onto the persisted record's status.
+   */
+  async processStatusCallback(payload, em) {
+    if (this.evaluatedTelemetryOptions.logging) {
+      this.openTelemetryCollector.info("Processing twilio status callback", {
+        messageSid: payload.MessageSid,
+        messageStatus: payload.MessageStatus
+      });
+    }
+    const smsRecord = await (em ?? this.em).findOneOrFail(
+      this.mappers.SmsRecordMapper.entity,
+      { providerMessageId: payload.MessageSid }
+    );
+    const record = smsRecord;
+    record.status = mapTwilioMessageStatus(payload.MessageStatus);
+    record.error = payload.ErrorMessage ?? null;
+    await (em ?? this.em).flush();
+    return this.mappers.SmsRecordMapper.toDto(
+      smsRecord
+    );
+  }
+};
+
+// services/index.ts
+export * from "@forklaunch/interfaces-messaging/interfaces";
+export * from "@forklaunch/interfaces-messaging/types";
+export {
+  TwilioSmsService,
+  mapTwilioMessageStatus
+};

package/lib/services/sms.service.d.ts

@@ -0,0 +1,38 @@
+import { IdDto } from '@forklaunch/common';
+import { MetricsDefinition, OpenTelemetryCollector, TelemetryOptions } from '@forklaunch/core/http';
+import { SmsStatusEnum } from '@forklaunch/implementation-messaging-base/enum';
+import { SmsMappers } from '@forklaunch/implementation-messaging-base/types';
+import { SmsService } from '@forklaunch/interfaces-messaging/interfaces';
+import { SendSmsDto } from '@forklaunch/interfaces-messaging/types';
+import { AnySchemaValidator } from '@forklaunch/validator';
+import { EntityManager } from '@mikro-orm/core';
+import { TwilioSmsDtos, TwilioSmsEntities, TwilioStatusCallbackDto } from '../domain/types/twilio.types';
+/**
+ * Maps a Twilio message status (from the Messages REST API or a delivery
+ * status callback) onto the canonical SmsStatusEnum.
+ */
+export declare const mapTwilioMessageStatus: (messageStatus: string) => SmsStatusEnum;
+export declare class TwilioSmsService<SchemaValidator extends AnySchemaValidator, Entities extends TwilioSmsEntities = TwilioSmsEntities, Dto extends TwilioSmsDtos = TwilioSmsDtos> implements SmsService<typeof SmsStatusEnum> {
+    readonly options?: {
+        telemetry?: TelemetryOptions;
+    } | undefined;
+    private evaluatedTelemetryOptions;
+    protected readonly accountSid: string;
+    protected readonly authToken: string;
+    protected readonly fromNumber: string;
+    em: EntityManager;
+    protected readonly openTelemetryCollector: OpenTelemetryCollector<MetricsDefinition>;
+    protected readonly schemaValidator: SchemaValidator;
+    protected readonly mappers: SmsMappers<typeof SmsStatusEnum, Entities, Dto>;
+    constructor(accountSid: string, authToken: string, fromNumber: string, em: EntityManager, openTelemetryCollector: OpenTelemetryCollector<MetricsDefinition>, schemaValidator: SchemaValidator, mappers: SmsMappers<typeof SmsStatusEnum, Entities, Dto>, options?: {
+        telemetry?: TelemetryOptions;
+    } | undefined);
+    sendSms(smsDto: SendSmsDto, em?: EntityManager, ...args: unknown[]): Promise<Dto['SmsRecordMapper']>;
+    getSmsRecord({ id }: IdDto, em?: EntityManager): Promise<Dto['SmsRecordMapper']>;
+    /**
+     * Maps a Twilio delivery-status callback (MessageStatus, MessageSid,
+     * ErrorMessage) onto the persisted record's status.
+     */
+    processStatusCallback(payload: TwilioStatusCallbackDto, em?: EntityManager): Promise<Dto['SmsRecordMapper']>;
+}
+//# sourceMappingURL=sms.service.d.ts.map

package/lib/services/sms.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sms.service.d.ts","sourceRoot":"","sources":["../../services/sms.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAEL,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,aAAa,EAAE,MAAM,gDAAgD,CAAC;AAC/E,OAAO,EAAE,UAAU,EAAE,MAAM,iDAAiD,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,MAAM,6CAA6C,CAAC;AACzE,OAAO,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAe,MAAM,iBAAiB,CAAC;AAE7D,OAAO,EAEL,aAAa,EACb,iBAAiB,EACjB,uBAAuB,EACxB,MAAM,8BAA8B,CAAC;AAGtC;;;GAGG;AACH,eAAO,MAAM,sBAAsB,kBAClB,MAAM,KACpB,aAmBF,CAAC;AAIF,qBAAa,gBAAgB,CAC3B,eAAe,SAAS,kBAAkB,EAC1C,QAAQ,SAAS,iBAAiB,GAAG,iBAAiB,EACtD,GAAG,SAAS,aAAa,GAAG,aAAa,CACzC,YAAW,UAAU,CAAC,OAAO,aAAa,CAAC;IAuBzC,QAAQ,CAAC,OAAO,CAAC,EAAE;QACjB,SAAS,CAAC,EAAE,gBAAgB,CAAC;KAC9B;IAvBH,OAAO,CAAC,yBAAyB,CAI/B;IACF,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IACtC,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IACrC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC/B,EAAE,EAAE,aAAa,CAAC;IACzB,SAAS,CAAC,QAAQ,CAAC,sBAAsB,EAAE,sBAAsB,CAAC,iBAAiB,CAAC,CAAC;IACrF,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IACpD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,aAAa,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IAE5E,YACE,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,aAAa,EACjB,sBAAsB,EAAE,sBAAsB,CAAC,iBAAiB,CAAC,EACjE,eAAe,EAAE,eAAe,EAChC,OAAO,EAAE,UAAU,CAAC,OAAO,aAAa,EAAE,QAAQ,EAAE,GAAG,CAAC,EAC/C,OAAO,CAAC,EAAE;QACjB,SAAS,CAAC,EAAE,gBAAgB,CAAC;KAC9B,YAAA,EAgBF;IAEK,OAAO,CACX,MAAM,EAAE,UAAU,EAClB,EAAE,CAAC,EAAE,aAAa,EAClB,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CA4DjC;IAEK,YAAY,CAChB,EAAE,EAAE,EAAE,EAAE,KAAK,EACb,EAAE,CAAC,EAAE,aAAa,GACjB,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAajC;IAED;;;OAGG;IACG,qBAAqB,CACzB,OAAO,EAAE,uBAAuB,EAChC,EAAE,CAAC,EAAE,aAAa,GACjB,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAyBjC;CACF"}

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@forklaunch/implementation-messaging-twilio",
+  "version": "1.0.0",
+  "description": "Twilio implementation for forklaunch messaging",
+  "homepage": "https://github.com/forklaunch/forklaunch-js#readme",
+  "bugs": {
+    "url": "https://github.com/forklaunch/forklaunch-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forklaunch/forklaunch-js.git"
+  },
+  "license": "MIT",
+  "author": "Forklift Technologies, Inc.",
+  "exports": {
+    "./enum": {
+      "types": "./lib/domain/enum/index.d.ts",
+      "import": "./lib/domain/enum/index.mjs",
+      "require": "./lib/domain/enum/index.js",
+      "default": "./lib/domain/enum/index.js"
+    },
+    "./schemas": {
+      "types": "./lib/domain/schemas/index.d.ts",
+      "import": "./lib/domain/schemas/index.mjs",
+      "require": "./lib/domain/schemas/index.js",
+      "default": "./lib/domain/schemas/index.js"
+    },
+    "./services": {
+      "types": "./lib/services/index.d.ts",
+      "import": "./lib/services/index.mjs",
+      "require": "./lib/services/index.js",
+      "default": "./lib/services/index.js"
+    },
+    "./types": {
+      "types": "./lib/domain/types/index.d.ts",
+      "import": "./lib/domain/types/index.mjs",
+      "require": "./lib/domain/types/index.js",
+      "default": "./lib/domain/types/index.js"
+    },
+    "./enum/*": {
+      "types": "./lib/domain/enum/*.d.ts"
+    },
+    "./schemas/*": {
+      "types": "./lib/domain/schemas/*.d.ts"
+    },
+    "./services/*": {
+      "types": "./lib/services/*.d.ts"
+    },
+    "./types/*": {
+      "types": "./lib/domain/types/*.d.ts"
+    },
+    "./persistence": {
+      "types": "./lib/persistence/entities/index.d.ts",
+      "import": "./lib/persistence/entities/index.mjs",
+      "require": "./lib/persistence/entities/index.js",
+      "default": "./lib/persistence/entities/index.js"
+    },
+    "./persistence/*": {
+      "types": "./lib/persistence/entities/*.d.ts"
+    }
+  },
+  "files": [
+    "lib/**"
+  ],
+  "dependencies": {
+    "@forklaunch/common": "^1.2.23",
+    "@forklaunch/core": "^1.5.15",
+    "@forklaunch/internal": "^1.2.24",
+    "@forklaunch/validator": "^1.2.24",
+    "@mikro-orm/core": "^7.1.11",
+    "@sinclair/typebox": "^0.34.52",
+    "ajv": "^8.20.0",
+    "zod": "^4.4.3",
+    "@forklaunch/implementation-messaging-base": "^1.0.0",
+    "@forklaunch/interfaces-messaging": "^1.0.0"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "depcheck": "^1.4.7",
+    "prettier": "^3.9.6",
+    "typedoc": "^0.28.20",
+    "@mikro-orm/sqlite": "^7.1.11",
+    "uuid": "^14.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsgo --noEmit && tsup persistence/entities/index.ts domain/schemas/index.ts services/index.ts domain/enum/index.ts domain/types/index.ts --format cjs,esm --no-splitting --tsconfig tsconfig.json --out-dir lib --clean && tsgo -p tsconfig.build.json --emitDeclarationOnly && if [ -f eject-package.bash ]; then pnpm package:eject; fi",
+    "clean": "rm -rf lib pnpm.lock.yaml node_modules",
+    "docs": "typedoc --out docs *",
+    "format": "prettier --ignore-path=.prettierignore --config .prettierrc '**/*.{ts,tsx,json}' --write",
+    "lint": "eslint . -c eslint.config.mjs",
+    "lint:fix": "eslint . -c eslint.config.mjs --fix",
+    "package:eject": "./eject-package.bash",
+    "publish:package": "./publish-package.bash",
+    "test": "vitest --passWithNoTests"
+  }
+}