sms-panel-manager 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,16 @@
+export { D as DateParameterOptions, I as InferActionPayload, N as NumberParameterOptions, P as ParameterDescriptor, a as ParameterMetadata, S as SerializableActionMetadata, b as SmsActionDefinition, c as SmsActionMap, d as SmsManager, e as SmsParameterMap, f as SmsParameterType, g as SmsSendCommand, h as SmsSendExecutor, i as SmsSendOptions, j as SmsSendResult, k as StringParameterOptions, l as createActionPayloadSchema, m as createSmsManager, n as defineSmsActions, s as serializeSmsActions, o as sms } from './manager-B3b12wET.cjs';
+export { C as CredentialEncryptionContext, a as CredentialEncryptionError, E as EncryptedCredentialEnvelope, b as EncryptionKeyring, I as InvalidParameterBindingError, O as OperationSnapshot, P as ParameterBinding, R as ResolvedSendConfiguration, S as SendConfigurationResolver, c as SendOperationStore, d as SmsOrchestrator, e as SmsOrchestratorOptions, f as applyParameterBindings, g as createEnvironmentKeyring, h as createStaticKeyring, i as decryptCredentials, j as encryptCredentials } from './encryption-BUH96uQn.cjs';
+export { C as CredentialVerificationResult, P as ProviderCallContext, a as ProviderCapabilities, b as ProviderSubmissionResult, c as ProviderTemplateCapability, d as ProviderTemplateSendInput, S as SmsProviderAdapter } from './provider-QoH6qlAe.cjs';
+import 'zod';
+
+declare class InvalidIranianMobileNumberError extends TypeError {
+    readonly code = "invalid_recipient";
+    constructor();
+}
+declare function normalizeIranianMobile(input: string): `+98${string}`;
+declare function toIranianLocalMobile(input: string): `09${string}`;
+
+declare function createPrivacyFingerprint(secret: Uint8Array, namespace: string, value: unknown): string;
+declare function fingerprintsEqual(left: string, right: string): boolean;
+
+export { InvalidIranianMobileNumberError, createPrivacyFingerprint, fingerprintsEqual, normalizeIranianMobile, toIranianLocalMobile };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { D as DateParameterOptions, I as InferActionPayload, N as NumberParameterOptions, P as ParameterDescriptor, a as ParameterMetadata, S as SerializableActionMetadata, b as SmsActionDefinition, c as SmsActionMap, d as SmsManager, e as SmsParameterMap, f as SmsParameterType, g as SmsSendCommand, h as SmsSendExecutor, i as SmsSendOptions, j as SmsSendResult, k as StringParameterOptions, l as createActionPayloadSchema, m as createSmsManager, n as defineSmsActions, s as serializeSmsActions, o as sms } from './manager-B3b12wET.js';
+export { C as CredentialEncryptionContext, a as CredentialEncryptionError, E as EncryptedCredentialEnvelope, b as EncryptionKeyring, I as InvalidParameterBindingError, O as OperationSnapshot, P as ParameterBinding, R as ResolvedSendConfiguration, S as SendConfigurationResolver, c as SendOperationStore, d as SmsOrchestrator, e as SmsOrchestratorOptions, f as applyParameterBindings, g as createEnvironmentKeyring, h as createStaticKeyring, i as decryptCredentials, j as encryptCredentials } from './encryption-Ckv6RYE0.js';
+export { C as CredentialVerificationResult, P as ProviderCallContext, a as ProviderCapabilities, b as ProviderSubmissionResult, c as ProviderTemplateCapability, d as ProviderTemplateSendInput, S as SmsProviderAdapter } from './provider-QoH6qlAe.js';
+import 'zod';
+
+declare class InvalidIranianMobileNumberError extends TypeError {
+    readonly code = "invalid_recipient";
+    constructor();
+}
+declare function normalizeIranianMobile(input: string): `+98${string}`;
+declare function toIranianLocalMobile(input: string): `09${string}`;
+
+declare function createPrivacyFingerprint(secret: Uint8Array, namespace: string, value: unknown): string;
+declare function fingerprintsEqual(left: string, right: string): boolean;
+
+export { InvalidIranianMobileNumberError, createPrivacyFingerprint, fingerprintsEqual, normalizeIranianMobile, toIranianLocalMobile };

package/dist/index.js

@@ -0,0 +1,546 @@
+import { z } from 'zod';
+import { createHmac, timingSafeEqual, randomUUID, randomBytes, createCipheriv, createDecipheriv } from 'crypto';
+
+// src/core/actions.ts
+var RESERVED_PARAMETER_KEYS = /* @__PURE__ */ new Set([
+  "recipient",
+  "idempotencyKey",
+  "signal",
+  "correlationId",
+  "metadata"
+]);
+function defineSmsActions(actions) {
+  for (const [actionKey, action] of Object.entries(actions)) {
+    if (!/^[a-z][a-z0-9_]*$/.test(actionKey)) {
+      throw new TypeError(
+        `Invalid SMS action key "${actionKey}". Use lower snake_case.`
+      );
+    }
+    for (const parameterKey of Object.keys(action.params)) {
+      if (RESERVED_PARAMETER_KEYS.has(parameterKey)) {
+        throw new TypeError(
+          `SMS action "${actionKey}" uses reserved parameter "${parameterKey}".`
+        );
+      }
+    }
+  }
+  return actions;
+}
+function createActionPayloadSchema(action) {
+  const shape = {
+    recipient: z.string().min(1)
+  };
+  for (const [key, parameter] of Object.entries(action.params)) {
+    shape[key] = parameter.schema;
+  }
+  return z.object(shape).strict();
+}
+function serializeSmsActions(actions) {
+  return Object.entries(actions).map(([key, action]) => ({
+    key,
+    title: action.title,
+    ...action.description === void 0 ? {} : { description: action.description },
+    parameters: Object.entries(action.params).map(
+      ([parameterKey, parameter]) => ({
+        key: parameterKey,
+        title: parameter.metadata.title,
+        ...parameter.metadata.description === void 0 ? {} : { description: parameter.metadata.description },
+        type: parameter.type,
+        required: !parameter.isOptional
+      })
+    )
+  }));
+}
+
+// src/core/bindings.ts
+var InvalidParameterBindingError = class extends TypeError {
+  code = "template_binding_invalid";
+  constructor(message) {
+    super(message);
+    this.name = "InvalidParameterBindingError";
+  }
+};
+function assertSafeKey(value, label) {
+  if (value.length === 0 || value === "__proto__" || value === "prototype" || value === "constructor") {
+    throw new InvalidParameterBindingError(`Unsafe or empty ${label}.`);
+  }
+}
+function applyParameterBindings(parameters, bindings) {
+  if (bindings.length === 0) {
+    throw new InvalidParameterBindingError(
+      "At least one parameter binding is required."
+    );
+  }
+  const kind = bindings[0]?.kind;
+  if (bindings.some((binding) => binding.kind !== kind)) {
+    throw new InvalidParameterBindingError(
+      "Parameter binding kinds cannot be mixed."
+    );
+  }
+  const sources = /* @__PURE__ */ new Set();
+  const destinations = /* @__PURE__ */ new Set();
+  for (const binding of bindings) {
+    assertSafeKey(binding.sourceParameter, "source parameter");
+    if (sources.has(binding.sourceParameter)) {
+      throw new InvalidParameterBindingError(
+        `Source parameter "${binding.sourceParameter}" is mapped more than once.`
+      );
+    }
+    sources.add(binding.sourceParameter);
+    const destination = binding.kind === "named" ? binding.providerParameter : binding.kind === "fixed-slot" ? binding.slot : binding.position;
+    if (typeof destination === "string")
+      assertSafeKey(destination, "destination");
+    if (destinations.has(destination)) {
+      throw new InvalidParameterBindingError(
+        `Provider destination "${String(destination)}" is mapped more than once.`
+      );
+    }
+    destinations.add(destination);
+  }
+  if (Object.keys(parameters).some((parameter) => !sources.has(parameter))) {
+    throw new InvalidParameterBindingError(
+      "Every supplied action parameter must be mapped exactly once."
+    );
+  }
+  if (kind === "ordered") {
+    const ordered = bindings.map((binding) => {
+      if (binding.kind !== "ordered")
+        throw new InvalidParameterBindingError("Invalid binding.");
+      if (!Number.isSafeInteger(binding.position) || binding.position < 1) {
+        throw new InvalidParameterBindingError(
+          "Ordered positions must be positive integers."
+        );
+      }
+      return binding;
+    }).sort((left, right) => left.position - right.position);
+    if (ordered.some((binding, index) => binding.position !== index + 1)) {
+      throw new InvalidParameterBindingError(
+        "Ordered positions must be contiguous from one."
+      );
+    }
+    const values = ordered.map(
+      (binding) => parameters[binding.sourceParameter]
+    );
+    while (values.at(-1) === void 0) values.pop();
+    if (values.some((value) => value === void 0)) {
+      throw new InvalidParameterBindingError(
+        "An omitted ordered parameter cannot precede a supplied parameter."
+      );
+    }
+    return values;
+  }
+  const result = /* @__PURE__ */ Object.create(null);
+  for (const binding of bindings) {
+    if (binding.kind === "ordered") {
+      throw new InvalidParameterBindingError("Invalid ordered binding state.");
+    }
+    const destination = binding.kind === "named" ? binding.providerParameter : binding.slot;
+    if (binding.sourceParameter in parameters) {
+      result[destination] = parameters[binding.sourceParameter];
+    }
+  }
+  return result;
+}
+
+// src/core/phone.ts
+var IRAN_MOBILE_LOCAL = /^09\d{9}$/;
+var InvalidIranianMobileNumberError = class extends TypeError {
+  code = "invalid_recipient";
+  constructor() {
+    super("Recipient must be a valid Iranian mobile number.");
+    this.name = "InvalidIranianMobileNumberError";
+  }
+};
+function normalizeIranianMobile(input) {
+  const normalized = input.trim().replace(/^0098/, "0").replace(/^\+98/, "0").replace(/^98/, "0");
+  if (!IRAN_MOBILE_LOCAL.test(normalized)) {
+    throw new InvalidIranianMobileNumberError();
+  }
+  return `+98${normalized.slice(1)}`;
+}
+function toIranianLocalMobile(input) {
+  const canonical = normalizeIranianMobile(input);
+  return `0${canonical.slice(3)}`;
+}
+
+// src/core/manager.ts
+function createSmsManager(options) {
+  return {
+    async send(actionKey, payload, sendOptions = {}) {
+      const action = options.actions[actionKey];
+      if (action === void 0) {
+        throw new TypeError(`Unknown SMS action "${actionKey}".`);
+      }
+      const validated = createActionPayloadSchema(action).parse(payload);
+      const { recipient, ...parameters } = validated;
+      return options.executor.execute({
+        actionKey,
+        recipient: normalizeIranianMobile(recipient),
+        parameters,
+        options: sendOptions
+      });
+    }
+  };
+}
+function canonicalize(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError("Cannot fingerprint a non-finite number.");
+    }
+    return value;
+  }
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) {
+      throw new TypeError("Cannot fingerprint an invalid date.");
+    }
+    return { $date: value.toISOString() };
+  }
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (typeof value === "object") {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new TypeError("Only plain objects can be fingerprinted.");
+    }
+    const result = {};
+    for (const key of Object.keys(value).sort()) {
+      if (key === "__proto__" || key === "constructor" || key === "prototype") {
+        throw new TypeError("Unsafe object key cannot be fingerprinted.");
+      }
+      const item = value[key];
+      if (item === void 0) {
+        throw new TypeError("Undefined values cannot be fingerprinted.");
+      }
+      result[key] = canonicalize(item);
+    }
+    return result;
+  }
+  throw new TypeError(`Unsupported fingerprint value: ${typeof value}.`);
+}
+function createPrivacyFingerprint(secret, namespace, value) {
+  if (secret.byteLength < 32) {
+    throw new TypeError("Fingerprint secret must contain at least 32 bytes.");
+  }
+  const canonical = JSON.stringify(canonicalize(value));
+  return createHmac("sha256", secret).update(namespace).update("\0").update(canonical).digest("base64url");
+}
+function fingerprintsEqual(left, right) {
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  return leftBuffer.byteLength === rightBuffer.byteLength && timingSafeEqual(leftBuffer, rightBuffer);
+}
+
+// src/core/orchestrator.ts
+function publicResult(operation) {
+  const status = operation.state === "reserved" || operation.state === "processing" ? "pending" : operation.state;
+  return {
+    operationId: operation.id,
+    status,
+    ...operation.providerMessageId === void 0 ? {} : { providerMessageId: operation.providerMessageId }
+  };
+}
+var SmsOrchestrator = class {
+  constructor(options) {
+    this.options = options;
+    this.scopeKey = options.scopeKey ?? "global";
+    this.retentionMs = options.operationRetentionMs ?? 30 * 24 * 60 * 60 * 1e3;
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+    if (this.retentionMs <= 0 || !Number.isSafeInteger(this.retentionMs)) {
+      throw new TypeError(
+        "Operation retention must be a positive integer of milliseconds."
+      );
+    }
+  }
+  options;
+  scopeKey;
+  retentionMs;
+  now;
+  async execute(command) {
+    if (command.options.idempotencyKey !== void 0 && (command.options.idempotencyKey.length < 1 || command.options.idempotencyKey.length > 200)) {
+      throw new TypeError(
+        "Idempotency key must contain between 1 and 200 characters."
+      );
+    }
+    const configuration = await this.options.configurations.resolve(
+      this.scopeKey,
+      command.actionKey
+    );
+    const providerParameters = applyParameterBindings(
+      command.parameters,
+      configuration.bindings
+    );
+    const idempotencyKey = command.options.idempotencyKey ?? randomUUID();
+    const expiresAt = new Date(this.now().getTime() + this.retentionMs);
+    const requestFingerprint = createPrivacyFingerprint(
+      this.options.fingerprintSecret,
+      "sms-send-request",
+      {
+        actionKey: command.actionKey,
+        recipient: command.recipient,
+        parameters: command.parameters,
+        actionDefinitionVersion: this.options.actionDefinitionVersion,
+        configurationId: configuration.id,
+        configurationVersion: configuration.version
+      }
+    );
+    const recipientFingerprint = createPrivacyFingerprint(
+      this.options.fingerprintSecret,
+      "sms-recipient",
+      command.recipient
+    );
+    const reservation = await this.options.operations.reserve({
+      scopeKey: this.scopeKey,
+      actionKey: command.actionKey,
+      actionDefinitionVersion: this.options.actionDefinitionVersion,
+      configurationVersion: configuration.version,
+      idempotencyKey,
+      requestFingerprint,
+      recipientFingerprint,
+      expiresAt
+    });
+    if (!reservation.created) return publicResult(reservation.operation);
+    await this.options.operations.beginAttempt({
+      operationId: reservation.operation.id,
+      providerConfigurationId: configuration.id,
+      adapterId: configuration.adapter.id,
+      expiresAt
+    });
+    let result;
+    try {
+      result = await configuration.adapter.sendTemplate(
+        configuration.credentials,
+        {
+          recipient: command.recipient,
+          template: configuration.template,
+          parameters: providerParameters,
+          ...command.options.idempotencyKey === void 0 ? {} : { clientReferenceId: command.options.idempotencyKey }
+        },
+        {
+          ...command.options.signal === void 0 ? {} : { signal: command.options.signal },
+          ...command.options.correlationId === void 0 ? {} : { correlationId: command.options.correlationId }
+        }
+      );
+    } catch {
+      result = { status: "unknown", code: "unknown_outcome" };
+    }
+    return publicResult(
+      await this.options.operations.completeAttempt(
+        reservation.operation.id,
+        result
+      )
+    );
+  }
+};
+function descriptor(type, schema, metadata) {
+  return {
+    type,
+    schema,
+    metadata,
+    isOptional: false,
+    optional() {
+      return optionalDescriptor(type, schema.optional(), metadata);
+    }
+  };
+}
+function optionalDescriptor(type, schema, metadata) {
+  return {
+    type,
+    schema,
+    metadata,
+    isOptional: true,
+    optional() {
+      return optionalDescriptor(type, schema.optional(), metadata);
+    }
+  };
+}
+function stringParameter(options) {
+  let schema = z.string();
+  if (options.minLength !== void 0) schema = schema.min(options.minLength);
+  if (options.maxLength !== void 0) schema = schema.max(options.maxLength);
+  if (options.pattern !== void 0) schema = schema.regex(options.pattern);
+  return descriptor("string", schema, options);
+}
+function numberParameter(options) {
+  let schema = z.number();
+  if (options.min !== void 0) schema = schema.min(options.min);
+  if (options.max !== void 0) schema = schema.max(options.max);
+  return descriptor("number", schema, options);
+}
+function integerParameter(options) {
+  let schema = z.number().int();
+  if (options.min !== void 0) schema = schema.min(options.min);
+  if (options.max !== void 0) schema = schema.max(options.max);
+  return descriptor("integer", schema, options);
+}
+function booleanParameter(options) {
+  return descriptor("boolean", z.boolean(), options);
+}
+function dateParameter(options) {
+  let schema = z.date();
+  if (options.min !== void 0) schema = schema.min(options.min);
+  if (options.max !== void 0) schema = schema.max(options.max);
+  return descriptor("date", schema, options);
+}
+function enumParameter(values, options) {
+  return descriptor("enum", z.enum(values), options);
+}
+var sms = {
+  string: stringParameter,
+  number: numberParameter,
+  integer: integerParameter,
+  boolean: booleanParameter,
+  date: dateParameter,
+  enum: enumParameter
+};
+var ALGORITHM = "aes-256-gcm";
+var NONCE_LENGTH = 12;
+var AUTH_TAG_LENGTH = 16;
+var KEY_LENGTH = 32;
+var CredentialEncryptionError = class extends Error {
+  code = "credential_encryption_failed";
+  constructor(message, options) {
+    super(message, options);
+    this.name = "CredentialEncryptionError";
+  }
+};
+function associatedData(context, keyId) {
+  return Buffer.from(
+    JSON.stringify({
+      type: "sms-provider-credentials",
+      configurationId: context.configurationId,
+      adapterId: context.adapterId,
+      scopeKey: context.scopeKey,
+      credentialRevision: context.credentialRevision,
+      schemaVersion: context.schemaVersion,
+      keyId
+    }),
+    "utf8"
+  );
+}
+function validKey(key, keyId) {
+  if (key === void 0) {
+    throw new CredentialEncryptionError(
+      `Encryption key "${keyId}" is unavailable.`
+    );
+  }
+  if (key.byteLength !== KEY_LENGTH) {
+    throw new CredentialEncryptionError(
+      `Encryption key "${keyId}" must be exactly 32 bytes.`
+    );
+  }
+  return Buffer.from(key);
+}
+async function encryptCredentials(credentials, context, keyring) {
+  const keyId = keyring.activeKeyId;
+  const key = validKey(await keyring.getKey(keyId), keyId);
+  const nonce = randomBytes(NONCE_LENGTH);
+  try {
+    const cipher = createCipheriv(ALGORITHM, key, nonce, {
+      authTagLength: AUTH_TAG_LENGTH
+    });
+    cipher.setAAD(associatedData(context, keyId));
+    const plaintext = Buffer.from(JSON.stringify(credentials), "utf8");
+    const ciphertext = Buffer.concat([
+      cipher.update(plaintext),
+      cipher.final()
+    ]);
+    return {
+      algorithm: ALGORITHM,
+      keyId,
+      configurationId: context.configurationId,
+      adapterId: context.adapterId,
+      scopeKey: context.scopeKey,
+      credentialRevision: context.credentialRevision,
+      nonce: nonce.toString("base64"),
+      ciphertext: ciphertext.toString("base64"),
+      authTag: cipher.getAuthTag().toString("base64"),
+      schemaVersion: context.schemaVersion
+    };
+  } catch (cause) {
+    throw new CredentialEncryptionError(
+      "Could not encrypt provider credentials.",
+      {
+        cause
+      }
+    );
+  } finally {
+    key.fill(0);
+  }
+}
+async function decryptCredentials(envelope, context, keyring) {
+  if (envelope.algorithm !== ALGORITHM) {
+    throw new CredentialEncryptionError(
+      "Unsupported credential encryption algorithm."
+    );
+  }
+  if (envelope.schemaVersion !== context.schemaVersion) {
+    throw new CredentialEncryptionError("Credential schema version mismatch.");
+  }
+  if (envelope.configurationId !== context.configurationId || envelope.adapterId !== context.adapterId || envelope.scopeKey !== context.scopeKey || envelope.credentialRevision !== context.credentialRevision) {
+    throw new CredentialEncryptionError(
+      "Credential encryption context mismatch."
+    );
+  }
+  const nonce = Buffer.from(envelope.nonce, "base64");
+  const authTag = Buffer.from(envelope.authTag, "base64");
+  if (nonce.byteLength !== NONCE_LENGTH || authTag.byteLength !== AUTH_TAG_LENGTH) {
+    throw new CredentialEncryptionError(
+      "Credential envelope has invalid nonce or tag length."
+    );
+  }
+  const key = validKey(await keyring.getKey(envelope.keyId), envelope.keyId);
+  try {
+    const decipher = createDecipheriv(ALGORITHM, key, nonce, {
+      authTagLength: AUTH_TAG_LENGTH
+    });
+    decipher.setAAD(associatedData(context, envelope.keyId));
+    decipher.setAuthTag(authTag);
+    const plaintext = Buffer.concat([
+      decipher.update(Buffer.from(envelope.ciphertext, "base64")),
+      decipher.final()
+    ]);
+    return JSON.parse(plaintext.toString("utf8"));
+  } catch (cause) {
+    throw new CredentialEncryptionError(
+      "Provider credentials could not be authenticated or decrypted.",
+      { cause }
+    );
+  } finally {
+    key.fill(0);
+  }
+}
+function createStaticKeyring(options) {
+  if (!(options.activeKeyId in options.keys)) {
+    throw new CredentialEncryptionError(
+      `Active encryption key "${options.activeKeyId}" is unavailable.`
+    );
+  }
+  const keys = new Map(
+    Object.entries(options.keys).map(([id, key]) => [id, validKey(key, id)])
+  );
+  return {
+    activeKeyId: options.activeKeyId,
+    getKey(keyId) {
+      const key = keys.get(keyId);
+      return key === void 0 ? void 0 : Buffer.from(key);
+    }
+  };
+}
+function createEnvironmentKeyring(options) {
+  const encoding = options.encoding ?? "base64";
+  return createStaticKeyring({
+    activeKeyId: options.activeKeyId,
+    keys: Object.fromEntries(
+      Object.entries(options.keys).map(([keyId, value]) => [
+        keyId,
+        Buffer.from(value, encoding)
+      ])
+    )
+  });
+}
+
+export { CredentialEncryptionError, InvalidIranianMobileNumberError, InvalidParameterBindingError, SmsOrchestrator, applyParameterBindings, createActionPayloadSchema, createEnvironmentKeyring, createPrivacyFingerprint, createSmsManager, createStaticKeyring, decryptCredentials, defineSmsActions, encryptCredentials, fingerprintsEqual, normalizeIranianMobile, serializeSmsActions, sms, toIranianLocalMobile };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map