sms-panel-manager 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 — 2026-11-06
+
+- Added typed actions and matching runtime validation.
+- Added credential encryption and privacy fingerprints.
+- Added Mongoose configuration, operation, attempt, TTL, and idempotency support.
+- Added one-attempt orchestration and parameter bindings.
+- Added offline-tested Ghasedak, Kavenegar, IPPanel, and FarazSMS adapters.
+- Added optional guarded NestJS integration.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sms-panel-manager contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# sms-panel-manager
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Backend-only, strongly typed transactional SMS orchestration for Node.js 20+.
+
+Actions live in version-controlled TypeScript, use the same definitions for runtime validation, and map semantic parameters to provider templates. The package includes secure Mongoose persistence and optional NestJS integration. It does not ship a frontend, authentication system, campaign engine, or complete OTP/session flow.
+
+## Status
+
+Version `0.1.0` is the initial development foundation release. Normal tests never contact an SMS provider.
+
+| Adapter                | Binding model              | Safe credential check |
+| ---------------------- | -------------------------- | --------------------- |
+| Ghasedak               | Ordered `param1`–`param10` | Account information   |
+| Kavenegar              | Fixed token slots          | Account information   |
+| IPPanel Edge           | Named pattern parameters   | Token/profile check   |
+| FarazSMS / IranPayamak | Named attributes           | Account balance       |
+
+Delivery polling is declared as a capability but is not yet exposed as a manager operation. MeliPayamak, SMS.ir, and Asanak are deferred until their API generation or authoritative public contract is locked.
+
+## Typed actions
+
+```ts
+import { createSmsManager, defineSmsActions, sms } from "sms-panel-manager";
+
+const actions = defineSmsActions({
+  package_posted: {
+    title: "ارسال مرسوله",
+    params: {
+      customerName: sms.string({ title: "نام مشتری", minLength: 1 }),
+      trackingCode: sms.string({ title: "کد رهگیری" }),
+      note: sms.string({ title: "یادداشت" }).optional(),
+    },
+  },
+});
+
+const manager = createSmsManager({
+  actions,
+  executor: {
+    async execute() {
+      return { operationId: "example", status: "submitted" };
+    },
+  },
+});
+
+await manager.send(
+  "package_posted",
+  {
+    recipient: "09123456789",
+    customerName: "علی",
+    trackingCode: "123456789",
+  },
+  { idempotencyKey: "shipment:123:posted:v1" },
+);
+```
+
+The first argument determines the exact second-argument type. The same definition produces strict Zod validation and safe administration metadata. V1 parameters are string, number, integer, boolean, date, and enum.
+
+## Sending behavior
+
+`SmsOrchestrator` performs one provider attempt. It reserves the logical operation before dispatch, fingerprints the request and recipient with HMAC-SHA-256, applies named/ordered/fixed-slot bindings, and never automatically falls back. An unexpected adapter exception becomes `unknown`, because retrying an ambiguous submission could send a duplicate SMS.
+
+Reusing an idempotency key with the same request returns its operation; using it with different data throws `idempotency_conflict`.
+
+## Mongoose persistence
+
+```ts
+import mongoose from "mongoose";
+import {
+  createSmsMongooseModels,
+  MongooseSendOperationStore,
+} from "sms-panel-manager/mongoose";
+
+const models = createSmsMongooseModels(mongoose.connection);
+const operations = new MongooseSendOperationStore(models);
+```
+
+The caller owns the connection; no hidden global connection is opened. Models cover provider/action configuration, logical operations, and physical attempts. Unique indexes enforce action configuration and idempotency. Retention uses TTL indexes.
+
+## Credential security
+
+Credentials use AES-256-GCM with unique nonces and authenticated configuration, adapter, scope, revision, schema, and key IDs.
+
+```ts
+import { createEnvironmentKeyring } from "sms-panel-manager";
+
+const keyring = createEnvironmentKeyring({
+  activeKeyId: "2026-01",
+  keys: { "2026-01": process.env.SMS_CONFIG_ENCRYPTION_KEY_BASE64! },
+});
+```
+
+Keys must decode to 32 bytes. Retain historical key IDs while old ciphertext exists, then re-encrypt. Never store the master key in MongoDB. Credentials, message bodies, semantic values, and raw provider responses are not retained by default.
+
+## Provider adapters
+
+```ts
+import { GhasedakAdapter } from "sms-panel-manager/providers";
+```
+
+Adapters use isolated Axios clients with HTTPS-only fixed base URLs, bounded timeouts, redirects disabled, abort signals, and Zod response parsing. Transport injection supports offline contract tests. Malformed success responses and transport exceptions become unknown outcomes rather than automatic retries.
+
+## NestJS
+
+```ts
+import {
+  createSmsManagerToken,
+  SmsPanelModule,
+  type InjectedSmsManager,
+} from "sms-panel-manager/nestjs";
+
+const SMS_MANAGER = createSmsManagerToken(actions);
+type ApplicationSmsManager = InjectedSmsManager<typeof SMS_MANAGER>;
+
+SmsPanelModule.forRoot({ actions, token: SMS_MANAGER, executor });
+```
+
+Administration controllers are absent by default. Enabling them without a host guard throws during registration:
+
+```ts
+SmsPanelModule.forRoot({
+  actions,
+  token: SMS_MANAGER,
+  executor,
+  admin: { enabled: true, guard: ApplicationAdminGuard },
+});
+```
+
+The foundation currently exposes guarded `GET /admin/sms/actions` metadata only. The package never invents host roles.
+
+## Development
+
+```sh
+npm install
+npm run check
+```
+
+Checks include strict TypeScript, ESLint, Vitest, a real local MongoDB concurrency test, ESM/CommonJS builds, declarations, and installed-tarball consumer checks. MongoDB integration is skipped if `/bin/mongod` is unavailable.
+
+No live SMS is sent in unit or CI tests. Live smoke tests require separate explicit authorization for provider, recipient, credentials, and cost.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,7 @@
+# Security policy
+
+Do not report provider credentials, customer phone numbers, message parameters, or private provider responses in a public issue. Rotate exposed credentials before using the repository owner's private security channel.
+
+The package treats provider credentials as write-only and does not retain message bodies or semantic values by default. Applications remain responsible for authentication, authorization, rate limiting, key storage, MongoDB security, and lawful recipient consent.
+
+Live provider tests and real SMS sends are outside the normal suite and require explicit operator authorization.

package/dist/encryption-BUH96uQn.d.cts

@@ -0,0 +1,119 @@
+import { h as SmsSendExecutor, g as SmsSendCommand, j as SmsSendResult } from './manager-B3b12wET.cjs';
+import { S as SmsProviderAdapter, b as ProviderSubmissionResult } from './provider-QoH6qlAe.cjs';
+
+type ParameterBinding = {
+    readonly kind: "named";
+    readonly providerParameter: string;
+    readonly sourceParameter: string;
+} | {
+    readonly kind: "ordered";
+    readonly position: number;
+    readonly sourceParameter: string;
+} | {
+    readonly kind: "fixed-slot";
+    readonly slot: string;
+    readonly sourceParameter: string;
+};
+declare class InvalidParameterBindingError extends TypeError {
+    readonly code = "template_binding_invalid";
+    constructor(message: string);
+}
+declare function applyParameterBindings(parameters: Readonly<Record<string, unknown>>, bindings: readonly ParameterBinding[]): Readonly<Record<string, unknown>> | readonly unknown[];
+
+interface ResolvedSendConfiguration {
+    readonly id: string;
+    readonly version: number;
+    readonly adapter: SmsProviderAdapter<Record<string, unknown>>;
+    readonly credentials: Record<string, unknown>;
+    readonly template: unknown;
+    readonly bindings: readonly ParameterBinding[];
+}
+interface SendConfigurationResolver {
+    resolve(scopeKey: string, actionKey: string): Promise<ResolvedSendConfiguration>;
+}
+interface OperationSnapshot {
+    readonly id: string;
+    readonly state: "reserved" | "processing" | "submitted" | "delivered" | "failed" | "unknown";
+    readonly providerMessageId?: string;
+}
+interface SendOperationStore {
+    reserve(input: {
+        readonly scopeKey: string;
+        readonly actionKey: string;
+        readonly actionDefinitionVersion: string;
+        readonly configurationVersion: number;
+        readonly idempotencyKey: string;
+        readonly requestFingerprint: string;
+        readonly recipientFingerprint: string;
+        readonly expiresAt: Date;
+    }): Promise<{
+        readonly created: boolean;
+        readonly operation: OperationSnapshot;
+    }>;
+    beginAttempt(input: {
+        readonly operationId: string;
+        readonly providerConfigurationId: string;
+        readonly adapterId: string;
+        readonly expiresAt: Date;
+    }): Promise<void>;
+    completeAttempt(operationId: string, result: ProviderSubmissionResult): Promise<OperationSnapshot>;
+}
+interface SmsOrchestratorOptions {
+    readonly scopeKey?: string;
+    readonly actionDefinitionVersion: string;
+    readonly fingerprintSecret: Uint8Array;
+    readonly operationRetentionMs?: number;
+    readonly configurations: SendConfigurationResolver;
+    readonly operations: SendOperationStore;
+    readonly now?: () => Date;
+}
+declare class SmsOrchestrator implements SmsSendExecutor {
+    private readonly options;
+    private readonly scopeKey;
+    private readonly retentionMs;
+    private readonly now;
+    constructor(options: SmsOrchestratorOptions);
+    execute(command: SmsSendCommand): Promise<SmsSendResult>;
+}
+
+interface EncryptionKeyring {
+    readonly activeKeyId: string;
+    getKey(keyId: string): Promise<Uint8Array | undefined> | Uint8Array | undefined;
+}
+interface CredentialEncryptionContext {
+    readonly configurationId: string;
+    readonly adapterId: string;
+    readonly scopeKey: string;
+    readonly credentialRevision: number;
+    readonly schemaVersion: number;
+}
+interface EncryptedCredentialEnvelope {
+    readonly algorithm: string;
+    readonly keyId: string;
+    readonly configurationId: string;
+    readonly adapterId: string;
+    readonly scopeKey: string;
+    readonly credentialRevision: number;
+    readonly nonce: string;
+    readonly ciphertext: string;
+    readonly authTag: string;
+    readonly schemaVersion: number;
+}
+declare class CredentialEncryptionError extends Error {
+    readonly code = "credential_encryption_failed";
+    constructor(message: string, options?: ErrorOptions);
+}
+declare function encryptCredentials(credentials: Readonly<Record<string, unknown>>, context: CredentialEncryptionContext, keyring: EncryptionKeyring): Promise<EncryptedCredentialEnvelope>;
+declare function decryptCredentials<T extends Record<string, unknown>>(envelope: EncryptedCredentialEnvelope, context: CredentialEncryptionContext, keyring: EncryptionKeyring): Promise<T>;
+declare function createStaticKeyring(options: {
+    readonly activeKeyId: string;
+    readonly keys: Readonly<Record<string, Uint8Array>>;
+}): EncryptionKeyring;
+declare function createEnvironmentKeyring(options: {
+    readonly activeKeyId: string;
+    readonly keys: Readonly<Record<string, string>>;
+    readonly encoding?: "base64" | "hex";
+}): EncryptionKeyring;
+
+export { InvalidParameterBindingError as I, CredentialEncryptionError as a, SmsOrchestrator as d, applyParameterBindings as f, createEnvironmentKeyring as g, createStaticKeyring as h, decryptCredentials as i, encryptCredentials as j };
+export type { CredentialEncryptionContext as C, EncryptedCredentialEnvelope as E, OperationSnapshot as O, ParameterBinding as P, ResolvedSendConfiguration as R, SendConfigurationResolver as S, EncryptionKeyring as b, SendOperationStore as c, SmsOrchestratorOptions as e };

package/dist/encryption-Ckv6RYE0.d.ts

@@ -0,0 +1,119 @@
+import { h as SmsSendExecutor, g as SmsSendCommand, j as SmsSendResult } from './manager-B3b12wET.js';
+import { S as SmsProviderAdapter, b as ProviderSubmissionResult } from './provider-QoH6qlAe.js';
+
+type ParameterBinding = {
+    readonly kind: "named";
+    readonly providerParameter: string;
+    readonly sourceParameter: string;
+} | {
+    readonly kind: "ordered";
+    readonly position: number;
+    readonly sourceParameter: string;
+} | {
+    readonly kind: "fixed-slot";
+    readonly slot: string;
+    readonly sourceParameter: string;
+};
+declare class InvalidParameterBindingError extends TypeError {
+    readonly code = "template_binding_invalid";
+    constructor(message: string);
+}
+declare function applyParameterBindings(parameters: Readonly<Record<string, unknown>>, bindings: readonly ParameterBinding[]): Readonly<Record<string, unknown>> | readonly unknown[];
+
+interface ResolvedSendConfiguration {
+    readonly id: string;
+    readonly version: number;
+    readonly adapter: SmsProviderAdapter<Record<string, unknown>>;
+    readonly credentials: Record<string, unknown>;
+    readonly template: unknown;
+    readonly bindings: readonly ParameterBinding[];
+}
+interface SendConfigurationResolver {
+    resolve(scopeKey: string, actionKey: string): Promise<ResolvedSendConfiguration>;
+}
+interface OperationSnapshot {
+    readonly id: string;
+    readonly state: "reserved" | "processing" | "submitted" | "delivered" | "failed" | "unknown";
+    readonly providerMessageId?: string;
+}
+interface SendOperationStore {
+    reserve(input: {
+        readonly scopeKey: string;
+        readonly actionKey: string;
+        readonly actionDefinitionVersion: string;
+        readonly configurationVersion: number;
+        readonly idempotencyKey: string;
+        readonly requestFingerprint: string;
+        readonly recipientFingerprint: string;
+        readonly expiresAt: Date;
+    }): Promise<{
+        readonly created: boolean;
+        readonly operation: OperationSnapshot;
+    }>;
+    beginAttempt(input: {
+        readonly operationId: string;
+        readonly providerConfigurationId: string;
+        readonly adapterId: string;
+        readonly expiresAt: Date;
+    }): Promise<void>;
+    completeAttempt(operationId: string, result: ProviderSubmissionResult): Promise<OperationSnapshot>;
+}
+interface SmsOrchestratorOptions {
+    readonly scopeKey?: string;
+    readonly actionDefinitionVersion: string;
+    readonly fingerprintSecret: Uint8Array;
+    readonly operationRetentionMs?: number;
+    readonly configurations: SendConfigurationResolver;
+    readonly operations: SendOperationStore;
+    readonly now?: () => Date;
+}
+declare class SmsOrchestrator implements SmsSendExecutor {
+    private readonly options;
+    private readonly scopeKey;
+    private readonly retentionMs;
+    private readonly now;
+    constructor(options: SmsOrchestratorOptions);
+    execute(command: SmsSendCommand): Promise<SmsSendResult>;
+}
+
+interface EncryptionKeyring {
+    readonly activeKeyId: string;
+    getKey(keyId: string): Promise<Uint8Array | undefined> | Uint8Array | undefined;
+}
+interface CredentialEncryptionContext {
+    readonly configurationId: string;
+    readonly adapterId: string;
+    readonly scopeKey: string;
+    readonly credentialRevision: number;
+    readonly schemaVersion: number;
+}
+interface EncryptedCredentialEnvelope {
+    readonly algorithm: string;
+    readonly keyId: string;
+    readonly configurationId: string;
+    readonly adapterId: string;
+    readonly scopeKey: string;
+    readonly credentialRevision: number;
+    readonly nonce: string;
+    readonly ciphertext: string;
+    readonly authTag: string;
+    readonly schemaVersion: number;
+}
+declare class CredentialEncryptionError extends Error {
+    readonly code = "credential_encryption_failed";
+    constructor(message: string, options?: ErrorOptions);
+}
+declare function encryptCredentials(credentials: Readonly<Record<string, unknown>>, context: CredentialEncryptionContext, keyring: EncryptionKeyring): Promise<EncryptedCredentialEnvelope>;
+declare function decryptCredentials<T extends Record<string, unknown>>(envelope: EncryptedCredentialEnvelope, context: CredentialEncryptionContext, keyring: EncryptionKeyring): Promise<T>;
+declare function createStaticKeyring(options: {
+    readonly activeKeyId: string;
+    readonly keys: Readonly<Record<string, Uint8Array>>;
+}): EncryptionKeyring;
+declare function createEnvironmentKeyring(options: {
+    readonly activeKeyId: string;
+    readonly keys: Readonly<Record<string, string>>;
+    readonly encoding?: "base64" | "hex";
+}): EncryptionKeyring;
+
+export { InvalidParameterBindingError as I, CredentialEncryptionError as a, SmsOrchestrator as d, applyParameterBindings as f, createEnvironmentKeyring as g, createStaticKeyring as h, decryptCredentials as i, encryptCredentials as j };
+export type { CredentialEncryptionContext as C, EncryptedCredentialEnvelope as E, OperationSnapshot as O, ParameterBinding as P, ResolvedSendConfiguration as R, SendConfigurationResolver as S, EncryptionKeyring as b, SendOperationStore as c, SmsOrchestratorOptions as e };