codeweaver 3.1.3 → 4.0.0

package/src/core/aws/message.ts

@@ -0,0 +1,259 @@
+import {
+  SNSClient,
+  PublishCommand,
+  GetSMSAttributesCommand,
+  SetSMSAttributesCommand,
+} from "@aws-sdk/client-sns";
+import {
+  SESv2Client,
+  SendEmailCommand,
+  ListEmailIdentitiesCommand,
+} from "@aws-sdk/client-sesv2";
+import {
+  CreatePlatformApplicationCommand,
+  CreatePlatformApplicationCommandInput,
+  CreatePlatformEndpointCommand,
+  CreatePlatformEndpointCommandInput,
+  PublishCommand as SNSPublishCommand,
+} from "@aws-sdk/client-sns";
+import { EmailMessage, PushPlatformArns, SMSMessage } from "./basic-types";
+
+/**
+ * Comprehensive TypeScript library for AWS SNS (SMS) and SES (Email) services.
+ * Provides simplified interfaces for sending messages with full TypeScript support.
+ *
+ * @example
+ * ```
+ * const messenger = new AWSMessenger("us-east-1");
+ * await messenger.sendSMS({ phoneNumber: '+1234567890', message: 'Hello!' });
+ * await messenger.sendEmail({
+ *   to: ['user@example.com'],
+ *   subject: 'Test',
+ *   textBody: 'Hello from SES!',
+ *   from: 'sender@verified.com'
+ * });
+ * ```
+ */
+export class Messenger {
+  public sns!: SNSClient;
+  public ses!: SESv2Client;
+
+  /**
+   * Creates an instance of AWSMessenger for SNS and SES operations.
+   * @param options - Configuration options.
+   * @param [options.region=us-east-1] - AWS region for operations.
+   */
+  public constructor(region?: string, ...args: any[]) {
+    if (region != null) {
+      this.sns = new SNSClient({ region, ...args });
+      this.ses = new SESv2Client({ region, ...args });
+    }
+  }
+
+  /**
+   * Sends an SMS message via AWS SNS.
+   * @param message - SMS configuration object.
+   * @returns Promise resolving to SNS publish response with MessageId.
+   * @throws Throws if phone number is invalid, quota exceeded, or permissions missing.
+   */
+  public async sendSMS(message: SMSMessage): Promise<any> {
+    const command = new PublishCommand({
+      PhoneNumber: message.phoneNumber,
+      Message: message.message,
+      MessageAttributes: message.attributes,
+    });
+    return this.sns.send(command);
+  }
+
+  /**
+   * Sends a bulk SMS to multiple phone numbers.
+   * @param messages - Array of SMS configuration objects.
+   * @returns Promise resolving to array of publish responses.
+   */
+  public async sendBulkSMS(messages: SMSMessage[]): Promise<any[]> {
+    const results = [];
+    for (const msg of messages) {
+      results.push(await this.sendSMS(msg));
+    }
+    return results;
+  }
+
+  /**
+   * Gets current SMS attributes (delivery status, monthly spend, etc.).
+   * @returns Promise resolving to SMS attributes map.
+   */
+  public async getSMSAttributes(): Promise<any> {
+    const command = new GetSMSAttributesCommand({});
+    const response = await this.sns.send(command);
+    return response.attributes || {};
+  }
+
+  /**
+   * Sets SMS attributes like DefaultSMSType (Transactional/Promotional).
+   * @param attributes - Map of SMS attributes to set.
+   * @returns Promise resolving to updated attributes.
+   * @example
+   * await messenger.setSMSAttributes({ DefaultSMSType: 'Transactional' });
+   */
+  public async setSMSAttributes(attributes: Record<string, string>): Promise<any> {
+    const command = new SetSMSAttributesCommand({ attributes });
+    return this.sns.send(command);
+  }
+
+  /**
+   * Sends an email via AWS SES v2.
+   * @param message - Email configuration object.
+   * @returns Promise resolving to SES send response with MessageId.
+   * @throws Throws if sender not verified, quota exceeded, or invalid recipients.
+   */
+  public async sendEmail(message: EmailMessage): Promise<any> {
+    const command = new SendEmailCommand({
+      FromEmailAddress: message.from,
+      Destination: {
+        ToAddresses: message.to,
+        CcAddresses: message.cc,
+        BccAddresses: message.bcc,
+      },
+      Content: {
+        Simple: {
+          Subject: { Data: message.subject, Charset: "UTF-8" },
+          Body: {
+            Text: message.textBody
+              ? { Data: message.textBody, Charset: "UTF-8" }
+              : undefined,
+            Html: message.htmlBody
+              ? { Data: message.htmlBody, Charset: "UTF-8" }
+              : undefined,
+          },
+        },
+      },
+      ReplyToAddresses: message.replyTo,
+    });
+    return this.ses.send(command);
+  }
+
+  /**
+   * Lists all SES verified email addresses.
+   * @returns Promise resolving to array of verified email addresses.
+   */
+  public async listVerifiedEmails(): Promise<string[]> {
+    const command = new ListEmailIdentitiesCommand({});
+    const response = await this.ses.send(command);
+    // Filter identities for email addresses only (exclude domains)
+    const emails = (response.EmailIdentities || [])
+      .filter((identity) => identity.IdentityType === "EMAIL_ADDRESS")
+      .map((identity) => identity.IdentityName || "");
+    return emails;
+  }
+
+  /** Optional: cache or store platform application ARNs by platform */
+  public pushPlatformArns: PushPlatformArns | undefined;
+
+  /**
+   * Creates a platform application for push notifications.
+   * You can store the resulting PlatformApplicationArn to reuse for endpoints.
+   * @param platform - 'APNS', 'APNS_SANDBOX', 'GCM' (FCM), etc.
+   * @param attributes - Optional attributes for the platform app (e.g., PlatformCredential, PlatformPrincipal)
+   * @param name - Optional logical name for internal tracking (not strictly required)
+   * @returns Promise resolving to the created PlatformApplicationArn
+   */
+  public async createPlatformApplication(
+    platform: string,
+    attributes: Record<string, string>
+  ): Promise<string> {
+    const command = new CreatePlatformApplicationCommand({
+      Name: platform + "_application_" + Date.now(),
+      Platform: platform,
+      Attributes: attributes,
+    } as CreatePlatformApplicationCommandInput);
+    const response = await this.sns.send(command);
+    const arn = response.PlatformApplicationArn;
+    // Optionally cache by platform
+    if (!this.pushPlatformArns) this.pushPlatformArns = {};
+    this.pushPlatformArns[platform] = arn || "";
+    return arn || "";
+  }
+
+  /**
+   * Creates an endpoint for a device token under a given platform application.
+   * @param platform - platform key, e.g., 'APNS', 'APNS_SANDBOX', 'GCM'
+   * @param token - device push token (device token for APNS, registration token for FCM)
+   * @param customUserData - optional custom data to associate with the endpoint
+   * @returns Promise resolving to the EndpointArn
+   */
+  public async createPlatformEndpoint(
+    platform: string,
+    token: string,
+    customUserData?: string
+  ): Promise<string> {
+    const appArn = this.pushPlatformArns?.[platform];
+    if (!appArn) {
+      throw new Error(
+        `Platform application ARN for ${platform} not found. Create it with createPlatformApplication first.`
+      );
+    }
+    const command = new CreatePlatformEndpointCommand({
+      PlatformApplicationArn: appArn,
+      Token: token,
+      UserData: customUserData,
+    } as CreatePlatformEndpointCommandInput);
+    const response = await this.sns.send(command);
+    return response.EndpointArn || "";
+  }
+
+  /**
+   * Publish a push notification to a specific endpoint.
+   * The Message structure uses platform-specific payloads for APNS/FCM, etc.
+   * @param endpointArn - The SNS EndpointArn to target
+   * @param message - The generic message payload
+   * @param subject - Optional subject (for some platforms)
+   * @returns Promise resolving to Publish response with MessageId
+   */
+  public async publishPushToEndpoint(
+    endpointArn: string,
+    message: {
+      // Common fields; you can structure this as needed
+      title?: string;
+      body?: string;
+      // Optional Apple/Google-specific overrides
+      apns?: any; // APNS payload
+      android?: any; // Android payload
+      default?: string;
+    }
+  ): Promise<any> {
+    // Build a platform-specific JSON payload. AWS SNS expects a JSON object
+    // with keys per platform, as a string under the "Message" field,
+    // and a "MessageStructure": "json"
+
+    const payload: any = {};
+
+    if (message.apns) payload.APNS = JSON.stringify(message.apns);
+    if (message.android) payload.GCM = JSON.stringify(message.android);
+    if (message.default) payload.default = message.default;
+    // Fallback to a simple default if no platform-specific payload provided
+    if (!payload.APNS && !payload.GCM && !payload.default) {
+      const simple = {
+        aps: {
+          alert: {
+            title: message.title || "",
+            body: message.body || "",
+          },
+        },
+      };
+      payload.APNS = JSON.stringify(simple);
+      // Some implementations also set GCM
+      payload.GCM = JSON.stringify({
+        notification: { title: message.title, body: message.body },
+      });
+    }
+
+    const command = new SNSPublishCommand({
+      TargetArn: endpointArn,
+      MessageStructure: "json",
+      Message: JSON.stringify(payload),
+    });
+
+    // Use PublishCommand alias to avoid naming confusion
+    return this.sns.send(command);
+  }
+}

package/src/core/aws/s3.ts

@@ -0,0 +1,136 @@
+import {
+  S3Client,
+  PutObjectCommand,
+  GetObjectCommand,
+  ListObjectsV2Command,
+  DeleteObjectCommand,
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { retry, RetryOptions } from "./utilities";
+import { DownloadParams, UploadParams } from "./basic-types";
+import fs from "fs";
+import util from "util";
+
+/**
+ * Client for interacting with AWS S3 buckets.
+ */
+export class S3 {
+  private client!: S3Client;
+
+  /**
+   * Constructor for S3Client.
+   * @param {string} [region] - The AWS region to use for the client.
+   * If not provided, the default region will be used.
+   */
+  public constructor(region?: string) {
+    if (region != null) {
+      this.client = new S3Client({ region });
+    }
+  }
+
+  /**
+   * Uploads a file to an S3 bucket.
+   * @param {UploadParams} params - The upload parameters.
+   * @param {string} params.bucket - The name of the S3 bucket to upload to.
+   * @param {string} params.key - The key of the object to create in the bucket.
+   * @param {string} params.filePath - The local path to the file to upload.
+   * @param {Record<string, any>} [params.extraArgs] - Additional parameters to pass to the PutObjectCommand.
+   * @returns {Promise<void>} A promise resolving when the upload is complete.
+   */
+  public async upload(
+    params: UploadParams,
+    retryOptions?: RetryOptions
+  ): Promise<void> {
+    const { bucket, key, filePath, extraArgs } = params;
+    const readFile = util.promisify(fs.promises.readFile);
+
+    const body = await readFile(filePath, undefined);
+
+    await retry(async () => {
+      await this.client.send(
+        new PutObjectCommand({
+          Bucket: bucket,
+          Key: key,
+          Body: body as any,
+          ...extraArgs,
+        })
+      );
+    }, retryOptions);
+  }
+
+  /**
+   * Downloads an object from an S3 bucket.
+   * @param {DownloadParams} params - The download parameters.
+   * @param {string} params.bucket - The name of the S3 bucket to download from.
+   * @param {string} params.key - The key of the object to download.
+   * @param {string} params.destPath - The local path to write the downloaded file to.
+   * @returns {Promise<void>} A promise resolving when the download is complete.
+   */
+  public async download(params: DownloadParams): Promise<void> {
+    const { bucket, key, destPath } = params;
+    const resp = await this.client.send(
+      new GetObjectCommand({ Bucket: bucket, Key: key })
+    );
+
+    const writeStream = fs.createWriteStream(destPath);
+
+    // resp.Body is a stream
+    if (resp.Body && "pipe" in resp.Body) {
+      await new Promise<void>((resolve, reject) => {
+        (resp.Body as any).pipe(writeStream);
+        writeStream.on("finish", () => resolve());
+        writeStream.on("error", (e) => reject(e));
+      });
+    } else {
+      // Fallback if Body is not streamable
+      const chunks: Buffer[] = [];
+      for await (const chunk of resp.Body as any)
+        chunks.push(Buffer.from(chunk));
+      await fs.promises.writeFile(destPath, Buffer.concat(chunks));
+    }
+  }
+
+  /**
+   * Lists the objects in an S3 bucket, optionally filtered by a prefix.
+   * @param {string} bucket - The name of the S3 bucket to list objects from.
+   * @param {string} [prefix] - The optional prefix to filter objects by.
+   * @returns {Promise<string[]>} A promise resolving with an array of object keys.
+   */
+  public async listObjects(bucket: string, prefix?: string): Promise<string[]> {
+    const cmd = new ListObjectsV2Command({ Bucket: bucket, Prefix: prefix });
+    const resp: any = await this.client.send(cmd);
+    const keys = (resp.Contents || []).map((c: any) => c.Key).filter(Boolean);
+    return keys;
+  }
+
+  /**
+   * Deletes an object from an S3 bucket.
+   * @param {string} bucket - The name of the S3 bucket to delete from.
+   * @param {string} key - The key of the object to delete.
+   * @returns {Promise<void>} A promise resolving when the delete is complete.
+   */
+  public async deleteObject(bucket: string, key: string): Promise<void> {
+    await this.client.send(
+      new DeleteObjectCommand({ Bucket: bucket, Key: key })
+    );
+  }
+
+  /**
+   * Generates a presigned URL for downloading an object from an S3 bucket.
+   * @param bucket The name of the S3 bucket to download from.
+   * @param key The key of the object to download.
+   * @param expirationInSeconds The number of seconds until the presigned URL expires.
+   *   Defaults to 3600 (1 hour).
+   * @returns A promise resolving to the presigned URL.
+   */
+  public async presignedUrl(
+    bucket: string,
+    key: string,
+    expirationInSeconds = 3600
+  ): Promise<string> {
+    const cmd = new GetObjectCommand({ Bucket: bucket, Key: key });
+    return await getSignedUrl(this.client, cmd, {
+      expiresIn: expirationInSeconds,
+    });
+  }
+}

package/src/core/aws/utilities.ts

@@ -0,0 +1,44 @@
+export type RetryOptions = {
+  retries?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  jitter?: boolean;
+};
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Simple exponential backoff retry wrapper.
+ * Retries the provided async function according to options.
+ */
+export async function retry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<T> {
+  const {
+    retries = 1,
+    baseDelayMs = 200,
+    maxDelayMs = 2000,
+    jitter = true,
+  } = options;
+
+  let attempt = 0;
+  while (true) {
+    try {
+      return await fn();
+    } catch (err) {
+      attempt++;
+      if (attempt > retries) {
+        throw err;
+      }
+      let delay = Math.min(maxDelayMs, baseDelayMs * Math.pow(2, attempt - 1));
+      if (jitter) {
+        const jitterMs = Math.random() * 100;
+        delay = Math.max(0, delay + jitterMs);
+      }
+      await sleep(delay);
+    }
+  }
+}

package/src/core/cache/basic-types.ts

@@ -0,0 +1,17 @@
+/**
+ * A simple cache interface.
+ */
+export interface AsyncCache<Entity> {
+  set: (key: string, value: Entity) => Promise<void>;
+  get: (key: string) => Promise<Entity | null>;
+  delete: (key: string) => Promise<void>;
+  has: (key: string) => Promise<boolean>;
+  clear: () => Promise<void>;
+}
+
+/**
+ * A function that takes a variable number of arguments and returns a string that uniquely identifies them.
+ */
+export type KeyResolver = <MethodArgs extends any[] = any[]>(
+  ...args: MethodArgs
+) => string;

package/src/core/cache/decorator.ts

@@ -0,0 +1,72 @@
+import { AsyncCache, KeyResolver } from "./basic-types";
+import { createMethodDecorator } from "@/core/helpers";
+
+/**
+ * Default key resolver for memoization.
+ * Takes a variable number of arguments and returns a string that uniquely identifies them.
+ * For objects, it uses JSON.stringify to convert the object to a string.
+ * For other types, it uses the primitive value of the argument.
+ * The resulting strings are joined with "|" to form the final key.
+ * @param {...args} MethodArgs
+ * @returns {string}
+ */
+function defaultKeyResolver<MethodArgs extends any[] = any[]>(
+  ...args: MethodArgs
+): string {
+  return args.length === 0
+    ? "key"
+    : args
+        .map((a) => (typeof a === "object" ? JSON.stringify(a) : a))
+        .join("|");
+}
+
+/**
+ * Decorator that memoizes a method, using a cache of type AsyncCache<Entity>
+ * and a key resolver of type KeyResolver.
+ * @returns {MethodDecorator}
+ */
+export function Memoize<Entity, MethodArgs extends any[] = any[]>(
+  cache: AsyncCache<Entity>,
+  keyResolver?: KeyResolver
+) {
+  return createMethodDecorator<
+    [AsyncCache<Entity>, KeyResolver | undefined],
+    MethodArgs
+  >(async ([cache, keyResolver], methodArgs, method, self) => {
+    keyResolver = keyResolver ?? defaultKeyResolver;
+    const key = keyResolver(...methodArgs);
+    const has = await cache?.has(key);
+    if (has) {
+      const value = await cache?.get(key);
+      return value;
+    } else {
+      const value = await method.apply(self, methodArgs);
+      await cache?.set(key, value as Entity);
+      return value;
+    }
+  })(cache, keyResolver);
+}
+
+/**
+ * Decorator that invalidates a cache of type AsyncCache<Entity> by key.
+ * @returns {MethodDecorator}
+ */
+export function Invalidate<Entity>(
+  cache: AsyncCache<Entity>,
+  shouldClearAll: boolean = true
+) {
+  return createMethodDecorator<
+    [AsyncCache<Entity>, boolean | true],
+    [string | undefined]
+  >(undefined, async (_value, [cache, shouldClearAll], [key]) => {
+    if (shouldClearAll === true) {
+      await cache.clear();
+    } else if (typeof key === "string" || typeof key === "number") {
+      await cache.delete(key);
+    } else {
+      throw new Error("The key must be string or number.");
+    }
+
+    return null;
+  })(cache, shouldClearAll);
+}

package/src/core/cache/index.ts

@@ -0,0 +1,4 @@
+export * from "./basic-types";
+export * from "./memory-cache.class";
+export * from "./redis-cache.class";
+export * from "./decorator";

package/src/core/cache/memory-cache.class.ts

@@ -0,0 +1,119 @@
+import { AsyncCache } from "./basic-types";
+
+/**
+ * A simple in-memory map-based cache implementing AsyncCache<T>.
+ * This is a straightforward wrapper around a Map<string, T>.
+ */
+export class MapAsyncCache<T> implements AsyncCache<T> {
+  private startTimeMs?: number;
+
+  public constructor(
+    private capacity?: number,
+    private durationMs?: number,
+    private cache?: Map<string, T>
+  ) {
+    this.startTimeMs = this.startTimeMs ?? Date.now();
+    this.durationMs = this.durationMs ?? Number.POSITIVE_INFINITY;
+    this.capacity = this.capacity ?? Number.POSITIVE_INFINITY;
+    this.cache = this.cache ?? new Map<string, T>();
+  }
+
+  public async size(): Promise<number> {
+    return await this.cache!.size;
+  }
+
+  public async keys(): Promise<string[]> {
+    return await Array.fromAsync(this.cache?.keys() ?? []);
+  }
+
+  public async values(): Promise<T[]> {
+    return await Array.fromAsync(this.cache?.values() ?? []);
+  }
+
+  public async entries(): Promise<[string, T][]> {
+    return await Array.fromAsync(this.cache?.entries() ?? []);
+  }
+
+  /**
+   * Whether the cache is still valid.
+   * This is a computed property that returns true if the cache
+   * has not yet expired, and false otherwise.
+   * @returns true if the cache is still valid, false otherwise
+   */
+  public get isValid(): boolean {
+    return this.startTimeMs! + this.durationMs! > Date.now();
+  }
+
+  /**
+   * Reset the cache if it has expired.
+   * @returns true if the cache was reset, false otherwise
+   */
+  public async resetIfExpired(): Promise<boolean> {
+    if (this.isValid == false) {
+      await this.cache?.clear();
+      this.startTimeMs = Date.now();
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Asynchronously set a value by key.
+   * @param key The cache key
+   * @param value The value to cache
+   */
+  public async set(key: string, value: T): Promise<void> {
+    if ((await this.resetIfExpired()) == true) return;
+    if (value != null) {
+      if (this.cache?.has(key)) {
+        await this.cache?.set(key, value);
+      } else {
+        if (
+          (this.capacity ?? Number.POSITIVE_INFINITY) > (this.cache?.size ?? 0)
+        ) {
+          await this.cache?.set(key, value);
+        }
+      }
+    } else {
+      await this.cache?.delete(key);
+    }
+  }
+
+  /**
+   * Asynchronously get a value by key.
+   *
+   * @param key The cache key
+   * - If the key exists, returns the value.
+   * - If the key does not exist, returns null.
+   */
+  public async get(key: string): Promise<T | null> {
+    if (await this.cache?.has(key)) {
+      return (await this.cache?.get(key)) ?? null;
+    }
+
+    return null;
+  }
+
+  /**
+   * Asynchronously delete a value by key.
+   */
+  public async delete(key: string): Promise<void> {
+    if ((await this.resetIfExpired()) == true) return;
+    await this.cache?.delete(key);
+  }
+
+  /**
+   * Asynchronously check if a key exists in the cache.
+   */
+  public async has(key: string): Promise<boolean> {
+    if ((await this.resetIfExpired()) == true) return false;
+    return (await this.cache?.has(key)) ?? false;
+  }
+
+  /**
+   * Asynchronously clear the cache.
+   */
+  public async clear(): Promise<void> {
+    await this.cache?.clear();
+  }
+}