SNS

Lightweight, dependency-free fake of AWS SNS that speaks the real SNS AWS Query wire protocol (form-encoded requests, XML responses, API version 2010-03-31), so application code using @aws-sdk/client-sns can run against it with zero cost and zero side effects.

Quick Start

Start the server:

import { SnsServer } from "./services/sns/src/server.js";

const server = new SnsServer(4569);
await server.start();
// ... use it ...
await server.stop();

Connect with the real AWS SDK client:

import {
  SNSClient,
  CreateTopicCommand,
  SubscribeCommand,
  PublishCommand,
} from "@aws-sdk/client-sns";

const sns = new SNSClient({
  region: "us-east-1",
  endpoint: "http://127.0.0.1:4569",
  credentials: { accessKeyId: "parlel", secretAccessKey: "parlel" },
});

// Create a topic
const { TopicArn } = await sns.send(new CreateTopicCommand({ Name: "events" }));

// Subscribe an SQS queue (auto-confirmed)
await sns.send(
  new SubscribeCommand({
    TopicArn,
    Protocol: "sqs",
    Endpoint: "arn:aws:sqs:us-east-1:000000000000:events-queue",
    ReturnSubscriptionArn: true,
  }),
);

// Publish a message
const { MessageId } = await sns.send(
  new PublishCommand({ TopicArn, Message: "hello world" }),
);
console.log(MessageId);

ARNs

• Topics: arn:aws:sns:{region}:{accountId}:{topicName}
• Subscriptions: arn:aws:sns:{region}:{accountId}:{topicName}:{uuid}
• Platform applications: arn:aws:sns:{region}:{accountId}:app/{platform}/{name}
• Platform endpoints: arn:aws:sns:{region}:{accountId}:endpoint/{platform}/{name}/{uuid}

The default region is us-east-1 and the default account id is 000000000000 (both configurable via the constructor: new SnsServer(port, { region, accountId, host })).

Internal endpoints (not part of SNS)

State can also be reset in-process with server.reset(). Published messages are captured in server.published for test assertions.

Implemented operations

All 42 operations exposed by @aws-sdk/client-sns v3 are implemented.

Topics

• CreateTopic — idempotent by name; supports FIFO (.fifo suffix), tags, and standard attributes
• DeleteTopic — idempotent; cascades to remove the topic's subscriptions
• ListTopics — paginated via NextToken
• GetTopicAttributes — returns TopicArn, Owner, DisplayName, Policy, EffectiveDeliveryPolicy, subscription counts, FIFO attributes, etc.
• SetTopicAttributes — mutable: Policy, DisplayName, DeliveryPolicy, KmsMasterKeyId, ContentBasedDeduplication, SignatureVersion, TracingConfig

Subscriptions

• Subscribe — sqs/lambda/application/firehose auto-confirm; http/https/email/email-json/sms go into pending confirmation
• ConfirmSubscription — confirms a pending subscription using its token (tokens are stored in server.pendingConfirmations)
• Unsubscribe
• ListSubscriptions — paginated
• ListSubscriptionsByTopic — paginated
• GetSubscriptionAttributes
• SetSubscriptionAttributes — mutable: DeliveryPolicy, RawMessageDelivery, FilterPolicy, FilterPolicyScope, RedrivePolicy, SubscriptionRoleArn

Publishing

• Publish — to TopicArn, TargetArn (platform endpoint), or PhoneNumber; supports Subject, MessageAttributes, MessageStructure: "json", FIFO MessageGroupId/MessageDeduplicationId
• PublishBatch — up to 10 entries; per-entry success/failure reporting

Permissions

• AddPermission
• RemovePermission

Tags

• TagResource
• UntagResource
• ListTagsForResource

Data protection policy

• GetDataProtectionPolicy
• PutDataProtectionPolicy

SMS

• GetSMSAttributes
• SetSMSAttributes
• CheckIfPhoneNumberIsOptedOut
• OptInPhoneNumber
• ListPhoneNumbersOptedOut
• ListOriginationNumbers

SMS sandbox

• GetSMSSandboxAccountStatus
• CreateSMSSandboxPhoneNumber
• VerifySMSSandboxPhoneNumber (default OTP is 123456)
• DeleteSMSSandboxPhoneNumber
• ListSMSSandboxPhoneNumbers

Platform applications & endpoints (mobile push)

• CreatePlatformApplication
• DeletePlatformApplication
• GetPlatformApplicationAttributes
• SetPlatformApplicationAttributes
• ListPlatformApplications
• CreatePlatformEndpoint — idempotent on (applicationArn, token)
• DeleteEndpoint
• GetEndpointAttributes
• SetEndpointAttributes
• ListEndpointsByPlatformApplication

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Error codes & shapes

Errors are returned as non-2xx HTTP responses with an XML body in the AWS Query error envelope:

<?xml version="1.0"?>
<ErrorResponse xmlns="http://sns.amazonaws.com/doc/2010-03-31/">
  <Error>
    <Type>Sender</Type>
    <Code>InvalidParameter</Code>
    <Message>Invalid parameter: Topic Name</Message>
  </Error>
  <RequestId>...</RequestId>
</ErrorResponse>

<Type> is Sender for client (4xx) faults and Receiver for server (5xx) faults.

Successful responses use the AWS Query success envelope, e.g.:

<?xml version="1.0"?>
<CreateTopicResponse xmlns="http://sns.amazonaws.com/doc/2010-03-31/">
  <CreateTopicResult>
    <TopicArn>arn:aws:sns:us-east-1:000000000000:events</TopicArn>
  </CreateTopicResult>
  <ResponseMetadata>
    <RequestId>...</RequestId>
  </ResponseMetadata>
</CreateTopicResponse>

Running the tests

npx vitest run tests/sns.test.ts

The test suite starts the server on port 14569, exercises every implemented operation (happy paths plus key edge cases), asserts the real SDK-parsed responses, and tears the server down in afterAll.

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

AWS_ACCESS_KEY_ID=parlel
AWS_SECRET_ACCESS_KEY=parlel
AWS_REGION=us-east-1
AWS_ENDPOINT_URL_SNS=http://parlel-bridge:4569
AWS_ENDPOINT_URL=http://parlel-bridge:4569