sqs-producer 3.4.0 → 5.0.0

package/.github/workflows/cla.yml

@@ -5,13 +5,18 @@ on:
   pull_request_target:
     types: [opened,closed,synchronize]
 
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
 jobs:
   CLAAssistant:
     runs-on: ubuntu-latest
     steps:
       - name: "CLA Check"
         if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
-        uses: contributor-assistant/github-action@v2.2.1
+        uses: contributor-assistant/github-action@v2.3.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PERSONAL_ACCESS_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

package/.github/workflows/codeql.yml

@@ -40,7 +40,7 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL

package/.github/workflows/coverage.yml

@@ -17,10 +17,10 @@ jobs:
         node-version: [18.x]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
 
@@ -28,7 +28,7 @@ jobs:
         run: npm ci
 
       - name: Report Coverage
-        uses: paambaati/codeclimate-action@v3.2.0
+        uses: paambaati/codeclimate-action@v5.0.0
         env:
           CC_TEST_REPORTER_ID: b7dd7a17709f29e70a936a1a9482a9d7c0da56915aec94382436d4e8f9bcb78e
         with:

package/.github/workflows/dependency-review.yml

@@ -0,0 +1,14 @@
+name: 'Dependency Review'
+on: [pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Checkout Repository'
+        uses: actions/checkout@v4
+      - name: 'Dependency Review'
+        uses: actions/dependency-review-action@v3

package/.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18.x
+          cache: 'npm'
+
+      - name: NPM Audit
+        run: npx audit-ci
+
+      - name: Install Node Modules
+        run: npm ci
+
+      - name: Build Docs
+        run: npm run generate-docs
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: './public'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

package/.github/workflows/lock-threads.yml

@@ -0,0 +1,29 @@
+name: "Lock Threads"
+
+on:
+  schedule:
+    - cron: "0 * * * *" # Once a day, at midnight UTC
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: lock
+
+jobs:
+  action:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: dessant/lock-threads@v4
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          issue-inactive-days: "30" # Lock issues after 30 days of being closed
+          pr-inactive-days: "5" # Lock closed PRs after 5 days. This ensures that issues that stem from a PR are opened as issues, rather than comments on the recently merged PR.
+          add-issue-labels: "outdated"
+          exclude-issue-created-before: "2023-01-01"
+          issue-comment: >
+            This issue has been closed for more than 30 days. If this issue is still occuring, please open a new issue with more recent context.
+          pr-comment: >
+            This pull request has already been merged/closed. If you experience issues related to these changes, please open a new issue referencing this pull request.

package/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish Package to npmjs
+on:
+  workflow_dispatch:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - name: Verify the integrity of provenance attestations and registry signatures for installed dependencies
+        run: npm audit signatures
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npx semantic-release

package/.github/workflows/stale.yml

@@ -7,7 +7,7 @@ jobs:
   stale:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@v6
+      - uses: actions/stale@v8
         with:
           stale-issue-message: 'This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.'
           stale-pr-message: 'This PR is stale because it has been open 45 days with no activity. Remove stale label or comment or this will be closed in 10 days.'
@@ -16,4 +16,9 @@ jobs:
           days-before-issue-stale: 30
           days-before-pr-stale: 45
           days-before-issue-close: 5
-          days-before-pr-close: 10
+          days-before-pr-close: 10
+          operations-per-run: 90
+          exempt-issue-labels: keep
+          exempt-pr-labels: keep
+          exempt-all-assignees: true
+          exempt-all-milestones: true

package/.github/workflows/test.yml

@@ -17,10 +17,10 @@ jobs:
         node-version: [18.x, 20.x]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
 

package/.prettierignore

@@ -1,4 +1,5 @@
 node_modules
 coverage
 bake-scripts
-dist
+dist
+public

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+## [5.0.0](https://github.com/bbc/sqs-producer/compare/v4.0.0...v5.0.0) (2024-03-11)
+
+
+### Features
+
+* updating ProducerOptions to use QueueUrl hostname ([#102](https://github.com/bbc/sqs-producer/issues/102)) ([370c363](https://github.com/bbc/sqs-producer/commit/370c3637ff161ee72bb2058b0e0dea7f77f9112f))
+
+
+### Chores
+
+* add documentation ([#106](https://github.com/bbc/sqs-producer/issues/106)) ([96dcb3b](https://github.com/bbc/sqs-producer/commit/96dcb3b4bce2882830568555206196dbb8875503))
+* **deps:** upgrading dependencies - march 24 ([#105](https://github.com/bbc/sqs-producer/issues/105)) ([4daa21b](https://github.com/bbc/sqs-producer/commit/4daa21b0b82a0f97321823f3537afe45c116df73))
+* downgrading @semantic-release/npm ([7836f3a](https://github.com/bbc/sqs-producer/commit/7836f3a5b6b4e887a727a98e476ac0dd97f26daf))
+* handle breaking changes ([4509173](https://github.com/bbc/sqs-producer/commit/4509173bfe38be97b5e4b1a3b2a56881109e8c84))
+* improve and update ci cd ([#107](https://github.com/bbc/sqs-producer/issues/107)) ([fe7e708](https://github.com/bbc/sqs-producer/commit/fe7e708435c0f1680ab060383f6edd0c00e9abee))

package/README.md

@@ -5,10 +5,12 @@
 [![Maintainability](https://api.codeclimate.com/v1/badges/5220635a4598c9f1a546/maintainability)](https://codeclimate.com/github/bbc/sqs-producer/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/5220635a4598c9f1a546/test_coverage)](https://codeclimate.com/github/bbc/sqs-producer/test_coverage)
 
-Enqueues messages onto a given SQS queue
+Enqueues messages onto a given SQS queue.
 
 ## Installation
 
+To install this package, enter the following command into your terminal (or the variant of whatever package manager you are using):
+
 ```
 npm install sqs-producer
 ```
@@ -24,6 +26,10 @@ npm install sqs-producer
 
 We will only support Node versions that are actively or security supported by the Node team. If you are still using an Node 14, please use a version of this library before the v3.2.1 release, if you are using Node 16, please use a version before the v3.3.0 release.
 
+## Documentation
+
+Visit [https://bbc.github.io/sqs-producer/](https://bbc.github.io/sqs-producer/) for the full API documentation.
+
 ## Usage
 
 ```js
@@ -78,7 +84,7 @@ await producer.send([
 //
 // deduplicationId can be excluded if content-based deduplication is enabled
 //
-// http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queue-recommendations.html
+// https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queue-recommendations.html
 await producer.send({
   id: 'testId',
   body: 'Hello world from our FIFO queue!',
@@ -89,7 +95,7 @@ await producer.send({
 
 ### Credentials
 
-By default the consumer will look for AWS credentials in the places [specified by the AWS SDK](http://docs.aws.amazon.com/AWSJavaScriptSDK/guide/node-configuring.html#Setting_AWS_Credentials). The simplest option is to export your credentials as environment variables:
+By default the consumer will look for AWS credentials in the places [specified by the AWS SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/guide/node-configuring.html#Setting_AWS_Credentials). The simplest option is to export your credentials as environment variables:
 
 ```bash
 export AWS_SECRET_ACCESS_KEY=...
@@ -123,7 +129,7 @@ await producer.send(['msg1', 'msg2']);
 
 ### Test
 
-```
+```bash
 npm test
 ```
 
@@ -131,7 +137,7 @@ npm test
 
 For coverage report, run the command:
 
-```
+```bash
 npm run coverage
 ```
 
@@ -139,10 +145,16 @@ npm run coverage
 
 To check for problems using ESLint
 
-```
+```bash
 npm run lint
 ```
 
 ## Contributing
 
-See [contributing guildlines](./.github/CONTRIBUTING.md)
+We welcome and appreciate contributions for anyone who would like to take the time to fix a bug or implement a new feature.
+
+But before you get started, [please read the contributing guidelines](https://github.com/bbc/sqs-producer/blob/main/.github/CONTRIBUTING.md) and [code of conduct](https://github.com/bbc/sqs-producer/blob/main/.github/CODE_OF_CONDUCT.md).
+
+## License
+
+SQS Producer is distributed under the Apache License, Version 2.0, see [LICENSE](./LICENSE) for more information.

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Error thrown when a message fails to send.
+ */
+export declare class FailedMessagesError extends Error {
+    /** Ids of messages that failed to send. */
+    failedMessages: string[];
+    /**
+     * @param failedMessages Ids of messages that failed to send.
+     */
+    constructor(failedMessages: string[]);
+}

package/dist/errors.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FailedMessagesError = void 0;
+/**
+ * Error thrown when a message fails to send.
+ */
+class FailedMessagesError extends Error {
+    /**
+     * @param failedMessages Ids of messages that failed to send.
+     */
+    constructor(failedMessages) {
+        super(`Failed to send messages: ${failedMessages.join(', ')}`);
+        this.failedMessages = failedMessages;
+    }
+}
+exports.FailedMessagesError = FailedMessagesError;

package/dist/format.d.ts

@@ -1,3 +1,8 @@
 import { SendMessageBatchRequestEntry } from '@aws-sdk/client-sqs';
 import { Message } from './types';
+/**
+ * Converts a message to a SendMessageBatchRequestEntry using the appropriate method
+ * depending on if the message is a string or an object
+ * @param message The message to convert
+ */
 export declare function toEntry(message: string | Message): SendMessageBatchRequestEntry;

package/dist/format.js

@@ -2,6 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toEntry = void 0;
 const validation_1 = require("./validation");
+/**
+ * Converts a message object to a SendMessageBatchRequestEntry
+ * @param message - The message to convert
+ * @returns The SendMessageBatchRequestEntry
+ * @throws Will throw an error if the message is invalid
+ */
 function entryFromObject(message) {
     if (!message.body) {
         throw new Error(`Object messages must have 'body' prop`);
@@ -50,12 +56,21 @@ function entryFromObject(message) {
     }
     return entry;
 }
+/**
+ * Converts a message string to a SendMessageBatchRequestEntry
+ * @param message The message to convert
+ */
 function entryFromString(message) {
     return {
         Id: message,
         MessageBody: message
     };
 }
+/**
+ * Converts a message to a SendMessageBatchRequestEntry using the appropriate method
+ * depending on if the message is a string or an object
+ * @param message The message to convert
+ */
 function toEntry(message) {
     if ((0, validation_1.isString)(message)) {
         return entryFromString(message);

package/dist/producer.d.ts

@@ -1,5 +1,8 @@
 import { SQSClient, SendMessageBatchResultEntry } from '@aws-sdk/client-sqs';
 import { Message, ProducerOptions } from './types';
+/**
+ * [Usage](https://bbc.github.io/sqs-producer/index.html#usage)
+ */
 export declare class Producer {
     static create: (options: ProducerOptions) => Producer;
     queueUrl: string;
@@ -7,8 +10,31 @@ export declare class Producer {
     sqs: SQSClient;
     region?: string;
     constructor(options: ProducerOptions);
+    /**
+     * Returns the number of messages in the queue.
+     * @returns A promise that resolves to the number of messages in the queue.
+     */
     queueSize(): Promise<number>;
+    /**
+     * Send a message to the queue.
+     * @param messages - A single message or an array of messages.
+     * @returns A promise that resolves to the result of the send operation.
+     */
     send(messages: string | Message | (string | Message)[]): Promise<SendMessageBatchResultEntry[]>;
+    /**
+     * Validate the producer options.
+     * @param options - The producer options to validate.
+     * @throws Error if any required options are missing or invalid.
+     */
     private validate;
+    /**
+     * Send a batch of messages to the queue.
+     * @param failedMessages - An array of failed message IDs.
+     * @param successfulMessages - An array of successful message results.
+     * @param messages - An array of messages to send.
+     * @param startIndex - The index of the first message in the batch.
+     * @returns A promise that resolves to the result of the send operation.
+     * @throws FailedMessagesError
+     */
     private sendBatch;
 }

package/dist/producer.js

@@ -3,16 +3,25 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Producer = void 0;
 const client_sqs_1 = require("@aws-sdk/client-sqs");
 const format_1 = require("./format");
+const errors_1 = require("./errors");
 const requiredOptions = ['queueUrl'];
+/**
+ * [Usage](https://bbc.github.io/sqs-producer/index.html#usage)
+ */
 class Producer {
     constructor(options) {
+        var _a;
         this.validate(options);
         this.queueUrl = options.queueUrl;
         this.batchSize = options.batchSize || 10;
         this.sqs =
             options.sqs ||
-                new client_sqs_1.SQSClient(Object.assign(Object.assign({}, options), { region: options.region || process.env.AWS_REGION || 'eu-west-1' }));
+                new client_sqs_1.SQSClient(Object.assign(Object.assign({}, options), { useQueueUrlAsEndpoint: (_a = options.useQueueUrlAsEndpoint) !== null && _a !== void 0 ? _a : true, region: options.region || process.env.AWS_REGION || 'eu-west-1' }));
     }
+    /**
+     * Returns the number of messages in the queue.
+     * @returns A promise that resolves to the number of messages in the queue.
+     */
     async queueSize() {
         const command = new client_sqs_1.GetQueueAttributesCommand({
             QueueUrl: this.queueUrl,
@@ -23,6 +32,11 @@ class Producer {
             result.Attributes &&
             result.Attributes.ApproximateNumberOfMessages);
     }
+    /**
+     * Send a message to the queue.
+     * @param messages - A single message or an array of messages.
+     * @returns A promise that resolves to the result of the send operation.
+     */
     async send(messages) {
         const failedMessages = [];
         const successfulMessages = [];
@@ -30,6 +44,11 @@ class Producer {
         const messagesArr = !Array.isArray(messages) ? [messages] : messages;
         return this.sendBatch(failedMessages, successfulMessages, messagesArr, startIndex);
     }
+    /**
+     * Validate the producer options.
+     * @param options - The producer options to validate.
+     * @throws Error if any required options are missing or invalid.
+     */
     validate(options) {
         for (const option of requiredOptions) {
             if (!options[option]) {
@@ -40,6 +59,15 @@ class Producer {
             throw new Error('SQS batchSize option must be between 1 and 10.');
         }
     }
+    /**
+     * Send a batch of messages to the queue.
+     * @param failedMessages - An array of failed message IDs.
+     * @param successfulMessages - An array of successful message results.
+     * @param messages - An array of messages to send.
+     * @param startIndex - The index of the first message in the batch.
+     * @returns A promise that resolves to the result of the send operation.
+     * @throws FailedMessagesError
+     */
     async sendBatch(failedMessages, successfulMessages, messages, startIndex) {
         var _a;
         const endIndex = startIndex + this.batchSize;
@@ -58,10 +86,14 @@ class Producer {
         if (failedMessagesBatch.length === 0) {
             return successfulMessagesBatch;
         }
-        throw new Error(`Failed to send messages: ${failedMessagesBatch.join(', ')}`);
+        throw new errors_1.FailedMessagesError(failedMessagesBatch);
     }
 }
 exports.Producer = Producer;
+/**
+ * Creates a new producer.
+ * @param options - The producer options.
+ */
 Producer.create = (options) => {
     return new Producer(options);
 };

package/dist/types.d.ts

@@ -1,16 +1,64 @@
 import { MessageAttributeValue, SQSClient } from '@aws-sdk/client-sqs';
 export interface ProducerOptions {
+    /**
+     * The URL of the queue to send messages to.
+     */
     queueUrl: string;
+    /**
+     * The number of messages to send in a single batch.
+     */
     batchSize?: number;
+    /**
+     * The SQS client to use. If not provided, a new client will be created.
+     */
     sqs?: SQSClient;
+    /**
+     * The AWS region to use. If not provided, the region will be determined
+     * from the `AWS_REGION` environment variable or will default to `eu-west-1.
+     */
     region?: string;
+    /**
+     * In cases where a QueueUrl is given as input, that
+     * will be preferred as the request endpoint.
+     *
+     * Set this value to false to ignore the QueueUrl and use the
+     * client's resolved endpoint, which may be a custom endpoint.
+     */
+    useQueueUrlAsEndpoint?: boolean;
 }
 export interface Message {
+    /**
+     * An identifier for the message. This must be unique within
+     * the batch of messages.
+     */
     id: string;
+    /**
+     * The messages contents.
+     */
     body: string;
+    /**
+     * This parameter applies only to FIFO (first-in-first-out) queues.
+     * When set messages that belong to the same message group are processed
+     * in a FIFO manner
+     */
     groupId?: string;
+    /**
+     * This parameter applies only to FIFO (first-in-first-out) queues.
+     * The token used for deduplication of messages within a 5-minute minimum
+     * deduplication interval. If a message with a particular id is sent successfully,
+     * subsequent messages with the same id are accepted
+     * successfully but aren't delivered.
+     */
     deduplicationId?: string;
+    /**
+     * The length of time, in seconds, for which to delay a specific message.
+     * Valid values: 0 to 900. Maximum: 15 minutes.
+     */
     delaySeconds?: number;
+    /**
+     * Each message attribute consists of a Name, Type, and Value. For more
+     * information, see [Amazon SQS message attributes](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-message-attributes.html).
+     */
     messageAttributes?: {
         [key: string]: MessageAttributeValue;
     };

package/dist/validation.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Checks if the value is a string
+ * @param value - The value to check
+ */
 export declare function isString(value: any): boolean;
+/**
+ * Checks if the value is an object
+ * @param value - The value to check
+ */
 export declare function isObject(value: any): boolean;
+/**
+ * Checks if a MessageAttribute is valid
+ * @param messageAttribute - The MessageAttribute to check
+ */
 export declare function isMessageAttributeValid(messageAttribute: any): boolean;

package/dist/validation.js

@@ -1,14 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isMessageAttributeValid = exports.isObject = exports.isString = void 0;
+/**
+ * Checks if the value is a string
+ * @param value - The value to check
+ */
 function isString(value) {
     return typeof value === 'string' || value instanceof String;
 }
 exports.isString = isString;
+/**
+ * Checks if the value is an object
+ * @param value - The value to check
+ */
 function isObject(value) {
     return value && typeof value === 'object' && value instanceof Object;
 }
 exports.isObject = isObject;
+/**
+ * Checks if a MessageAttribute is valid
+ * @param messageAttribute - The MessageAttribute to check
+ */
 function isMessageAttributeValid(messageAttribute) {
     if (!messageAttribute.DataType) {
         throw new Error('A MessageAttribute must have a DataType key');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqs-producer",
-  "version": "3.4.0",
+  "version": "5.0.0",
   "description": "Enqueues messages onto a given SQS queue",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,13 +11,14 @@
     "lcov": "c8 mocha && c8 report --reporter=lcov",
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --fix",
-    "format": "prettier --loglevel warn --write \"**/*.{js,json,jsx,md,ts,tsx,html}\"",
+    "format": "prettier --log-level warn --write \"**/*.{js,json,jsx,md,ts,tsx,html}\"",
     "format:check": "prettier --check \"**/*.{js,json,jsx,md,ts,tsx,html}\"",
     "build": "npm run clean && tsc",
     "prepublishOnly": "npm run build",
     "pretest": "npm run build",
     "watch": "tsc --watch",
-    "clean": "rm -fr dist/*"
+    "clean": "rm -fr dist/*",
+    "generate-docs": "typedoc"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -36,29 +37,125 @@
     "producer",
     "queue"
   ],
-  "homepage": "https://github.com/bbc/sqs-producer",
+  "homepage": "https://bbc.github.io/sqs-producer/",
+  "publishConfig": {
+    "provenance": true
+  },
+  "release": {
+    "branches": [
+      "main",
+      {
+        "name": "canary",
+        "prerelease": true
+      }
+    ],
+    "plugins": [
+      [
+        "@semantic-release/commit-analyzer",
+        {
+          "preset": "conventionalcommits",
+          "releaseRules": [
+            {
+              "type": "breaking",
+              "release": "major"
+            },
+            {
+              "type": "feat",
+              "release": "minor"
+            },
+            {
+              "type": "chore",
+              "release": "patch"
+            },
+            {
+              "type": "fix",
+              "release": "patch"
+            },
+            {
+              "type": "docs",
+              "release": "patch"
+            },
+            {
+              "type": "refactor",
+              "release": "patch"
+            },
+            {
+              "type": "test",
+              "release": "patch"
+            }
+          ]
+        }
+      ],
+      [
+        "@semantic-release/release-notes-generator",
+        {
+          "preset": "conventionalcommits",
+          "presetConfig": {
+            "types": [
+              {
+                "type": "feat",
+                "section": "Features"
+              },
+              {
+                "type": "fix",
+                "section": "Bug Fixes"
+              },
+              {
+                "type": "chore",
+                "section": "Chores"
+              },
+              {
+                "type": "docs",
+                "section": "Documentation"
+              },
+              {
+                "type": "refactor",
+                "section": "Refactors"
+              },
+              {
+                "type": "test",
+                "section": "Tests"
+              }
+            ]
+          }
+        }
+      ],
+      "@semantic-release/changelog",
+      "@semantic-release/github",
+      "@semantic-release/npm"
+    ]
+  },
   "devDependencies": {
-    "@types/chai": "^4.3.9",
-    "@types/debug": "^4.1.10",
-    "@types/mocha": "^10.0.3",
-    "@types/node": "^20.8.7",
-    "@types/sinon": "^10.0.20",
-    "chai": "^4.3.10",
-    "eslint": "^8.52.0",
-    "eslint-config-iplayer": "^9.1.0",
-    "eslint-config-prettier": "^9.0.0",
-    "mocha": "^10.2.0",
-    "c8": "^8.0.1",
-    "prettier": "^3.0.3",
-    "sinon": "^17.0.0",
-    "ts-node": "^10.9.1",
-    "typescript": "^5.2.2"
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^11.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^9.2.6",
+    "@semantic-release/npm": "11.0.2",
+    "@semantic-release/release-notes-generator": "^12.1.0",
+    "@types/chai": "^4.3.12",
+    "@types/debug": "^4.1.12",
+    "@types/mocha": "^10.0.6",
+    "@types/node": "^20.11.25",
+    "@types/sinon": "^17.0.3",
+    "chai": "^4.4.1",
+    "conventional-changelog-conventionalcommits": "^7.0.2",
+    "eslint": "^8.57.0",
+    "eslint-config-iplayer": "^9.2.0",
+    "eslint-config-prettier": "^9.1.0",
+    "mocha": "^10.3.0",
+    "c8": "^9.1.0",
+    "prettier": "^3.2.5",
+    "semantic-release": "^23.0.0",
+    "sinon": "^17.0.1",
+    "ts-node": "^10.9.2",
+    "typedoc": "^0.25.12",
+    "typescript": "^5.4.2"
   },
   "dependencies": {
-    "@aws-sdk/client-sqs": "^3.428.0"
+    "@aws-sdk/client-sqs": "^3.529.1"
   },
   "peerDependencies": {
-    "@aws-sdk/client-sqs": "^3.428.0"
+    "@aws-sdk/client-sqs": "^3.529.1"
   },
   "mocha": {
     "spec": "test/**/**/*.test.ts",

package/src/errors.ts

@@ -0,0 +1,14 @@
+/**
+ * Error thrown when a message fails to send.
+ */
+export class FailedMessagesError extends Error {
+  /** Ids of messages that failed to send. */
+  public failedMessages: string[];
+  /**
+   * @param failedMessages Ids of messages that failed to send.
+   */
+  constructor(failedMessages: string[]) {
+    super(`Failed to send messages: ${failedMessages.join(', ')}`);
+    this.failedMessages = failedMessages;
+  }
+}

package/src/format.ts

@@ -2,6 +2,12 @@ import { SendMessageBatchRequestEntry } from '@aws-sdk/client-sqs';
 import { Message } from './types';
 import { isObject, isString, isMessageAttributeValid } from './validation';
 
+/**
+ * Converts a message object to a SendMessageBatchRequestEntry
+ * @param message - The message to convert
+ * @returns The SendMessageBatchRequestEntry
+ * @throws Will throw an error if the message is invalid
+ */
 function entryFromObject(message: Message): SendMessageBatchRequestEntry {
   if (!message.body) {
     throw new Error(`Object messages must have 'body' prop`);
@@ -69,6 +75,10 @@ function entryFromObject(message: Message): SendMessageBatchRequestEntry {
   return entry;
 }
 
+/**
+ * Converts a message string to a SendMessageBatchRequestEntry
+ * @param message The message to convert
+ */
 function entryFromString(message: string): SendMessageBatchRequestEntry {
   return {
     Id: message,
@@ -76,6 +86,11 @@ function entryFromString(message: string): SendMessageBatchRequestEntry {
   };
 }
 
+/**
+ * Converts a message to a SendMessageBatchRequestEntry using the appropriate method
+ * depending on if the message is a string or an object
+ * @param message The message to convert
+ */
 export function toEntry(
   message: string | Message
 ): SendMessageBatchRequestEntry {

package/src/producer.ts

@@ -6,9 +6,13 @@ import {
 } from '@aws-sdk/client-sqs';
 import { Message, ProducerOptions } from './types';
 import { toEntry } from './format';
+import { FailedMessagesError } from './errors';
 
 const requiredOptions = ['queueUrl'];
 
+/**
+ * [Usage](https://bbc.github.io/sqs-producer/index.html#usage)
+ */
 export class Producer {
   static create: (options: ProducerOptions) => Producer;
   queueUrl: string;
@@ -24,10 +28,15 @@ export class Producer {
       options.sqs ||
       new SQSClient({
         ...options,
+        useQueueUrlAsEndpoint: options.useQueueUrlAsEndpoint ?? true,
         region: options.region || process.env.AWS_REGION || 'eu-west-1'
       });
   }
 
+  /**
+   * Returns the number of messages in the queue.
+   * @returns A promise that resolves to the number of messages in the queue.
+   */
   async queueSize(): Promise<number> {
     const command = new GetQueueAttributesCommand({
       QueueUrl: this.queueUrl,
@@ -43,6 +52,11 @@ export class Producer {
     );
   }
 
+  /**
+   * Send a message to the queue.
+   * @param messages - A single message or an array of messages.
+   * @returns A promise that resolves to the result of the send operation.
+   */
   async send(
     messages: string | Message | (string | Message)[]
   ): Promise<SendMessageBatchResultEntry[]> {
@@ -59,6 +73,11 @@ export class Producer {
     );
   }
 
+  /**
+   * Validate the producer options.
+   * @param options - The producer options to validate.
+   * @throws Error if any required options are missing or invalid.
+   */
   private validate(options: ProducerOptions): void {
     for (const option of requiredOptions) {
       if (!options[option]) {
@@ -70,6 +89,15 @@ export class Producer {
     }
   }
 
+  /**
+   * Send a batch of messages to the queue.
+   * @param failedMessages - An array of failed message IDs.
+   * @param successfulMessages - An array of successful message results.
+   * @param messages - An array of messages to send.
+   * @param startIndex - The index of the first message in the batch.
+   * @returns A promise that resolves to the result of the send operation.
+   * @throws FailedMessagesError
+   */
   private async sendBatch(
     failedMessages?: string[],
     successfulMessages?: SendMessageBatchResultEntry[],
@@ -104,12 +132,14 @@ export class Producer {
     if (failedMessagesBatch.length === 0) {
       return successfulMessagesBatch;
     }
-    throw new Error(
-      `Failed to send messages: ${failedMessagesBatch.join(', ')}`
-    );
+    throw new FailedMessagesError(failedMessagesBatch);
   }
 }
 
+/**
+ * Creates a new producer.
+ * @param options - The producer options.
+ */
 Producer.create = (options: ProducerOptions): Producer => {
   return new Producer(options);
 };

package/src/types.ts

@@ -1,17 +1,65 @@
 import { MessageAttributeValue, SQSClient } from '@aws-sdk/client-sqs';
 
 export interface ProducerOptions {
+  /**
+   * The URL of the queue to send messages to.
+   */
   queueUrl: string;
+  /**
+   * The number of messages to send in a single batch.
+   */
   batchSize?: number;
+  /**
+   * The SQS client to use. If not provided, a new client will be created.
+   */
   sqs?: SQSClient;
+  /**
+   * The AWS region to use. If not provided, the region will be determined
+   * from the `AWS_REGION` environment variable or will default to `eu-west-1.
+   */
   region?: string;
+  /**
+   * In cases where a QueueUrl is given as input, that
+   * will be preferred as the request endpoint.
+   *
+   * Set this value to false to ignore the QueueUrl and use the
+   * client's resolved endpoint, which may be a custom endpoint.
+   */
+  useQueueUrlAsEndpoint?: boolean;
 }
 
 export interface Message {
+  /**
+   * An identifier for the message. This must be unique within
+   * the batch of messages.
+   */
   id: string;
+  /**
+   * The messages contents.
+   */
   body: string;
+  /**
+   * This parameter applies only to FIFO (first-in-first-out) queues.
+   * When set messages that belong to the same message group are processed
+   * in a FIFO manner
+   */
   groupId?: string;
+  /**
+   * This parameter applies only to FIFO (first-in-first-out) queues.
+   * The token used for deduplication of messages within a 5-minute minimum
+   * deduplication interval. If a message with a particular id is sent successfully,
+   * subsequent messages with the same id are accepted
+   * successfully but aren't delivered.
+   */
   deduplicationId?: string;
+  /**
+   * The length of time, in seconds, for which to delay a specific message.
+   * Valid values: 0 to 900. Maximum: 15 minutes.
+   */
   delaySeconds?: number;
+  /**
+   * Each message attribute consists of a Name, Type, and Value. For more
+   * information, see [Amazon SQS message attributes](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-message-attributes.html).
+   */
   messageAttributes?: { [key: string]: MessageAttributeValue };
 }

package/src/validation.ts

@@ -1,11 +1,23 @@
+/**
+ * Checks if the value is a string
+ * @param value - The value to check
+ */
 export function isString(value: any): boolean {
   return typeof value === 'string' || value instanceof String;
 }
 
+/**
+ * Checks if the value is an object
+ * @param value - The value to check
+ */
 export function isObject(value: any): boolean {
   return value && typeof value === 'object' && value instanceof Object;
 }
 
+/**
+ * Checks if a MessageAttribute is valid
+ * @param messageAttribute - The MessageAttribute to check
+ */
 export function isMessageAttributeValid(messageAttribute: any): boolean {
   if (!messageAttribute.DataType) {
     throw new Error('A MessageAttribute must have a DataType key');

package/typedoc.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "sort": ["kind", "instance-first", "required-first", "alphabetical"],
+  "treatWarningsAsErrors": false,
+  "searchInComments": true,
+  "entryPoints": ["./src/index.ts"],
+  "out": "public",
+  "name": "SQS Producer",
+  "hideGenerator": true,
+  "navigationLinks": {
+    "GitHub": "https://github.com/bbc/sqs-producer"
+  }
+}