or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-configuration.mddata-protection.mdindex.mdmessage-publishing.mdpagination.mdpermission-management.mdplatform-applications.mdresource-tagging.mdsms-management.mdsubscription-management.mdtopic-management.md
tile.json

topic-management.mddocs/

Topic Management

SNS topic management provides comprehensive functionality for creating, configuring, deleting, and listing topics with full attribute control and tagging support.

Capabilities

Create Topic

Creates a new SNS topic with optional attributes, tags, and data protection policy.

/**
 * Creates a topic to which notifications can be published
 * Supports standard and FIFO topics with comprehensive configuration
 */
class CreateTopicCommand {
  constructor(input: CreateTopicInput);
}

interface CreateTopicInput {
  /** Name of the topic (required) */
  Name: string | undefined;
  /** Topic attributes for configuration */
  Attributes?: Record<string, string> | undefined;
  /** Tags to assign to the topic */
  Tags?: Tag[] | undefined;
  /** Data protection policy JSON string */
  DataProtectionPolicy?: string | undefined;
}

interface CreateTopicResponse {
  /** ARN of the created topic */
  TopicArn?: string;
}

type TopicAttributesMap = Record<string, string>;

Usage Examples:

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

const client = new SNSClient({ region: "us-east-1" });

// Basic topic creation
const basicTopic = await client.send(new CreateTopicCommand({
  Name: "MyTopic"
}));

// Topic with attributes and tags
const advancedTopic = await client.send(new CreateTopicCommand({
  Name: "MyAdvancedTopic",
  Attributes: {
    DisplayName: "My Advanced Topic",
    DeliveryPolicy: JSON.stringify({
      http: {
        defaultHealthyRetryPolicy: {
          minDelayTarget: 20,
          maxDelayTarget: 20,
          numRetries: 3
        }
      }
    })
  },
  Tags: [
    { Key: "Environment", Value: "Production" },
    { Key: "Owner", Value: "MyTeam" }
  ]
}));

// FIFO topic creation
const fifoTopic = await client.send(new CreateTopicCommand({
  Name: "MyTopic.fifo",
  Attributes: {
    FifoTopic: "true",
    ContentBasedDeduplication: "true"
  }
}));

Delete Topic

Deletes an SNS topic and all its subscriptions.

/**
 * Deletes a topic and all its subscriptions
 * This action is irreversible
 */
class DeleteTopicCommand {
  constructor(input: DeleteTopicInput);
}

interface DeleteTopicInput {
  /** ARN of the topic to delete */
  TopicArn: string;
}

Usage Example:

await client.send(new DeleteTopicCommand({
  TopicArn: "arn:aws:sns:us-east-1:123456789012:MyTopic"
}));

Get Topic Attributes

Retrieves attributes and configuration for a specific topic.

/**
 * Returns topic attributes including configuration and statistics
 */
class GetTopicAttributesCommand {
  constructor(input: GetTopicAttributesInput);
}

interface GetTopicAttributesInput {
  /** ARN of the topic */
  TopicArn: string;
}

interface GetTopicAttributesResponse {
  /** Map of attribute names to values */
  Attributes?: TopicAttributesMap;
}

Common Topic Attributes:

  • TopicArn: The topic's ARN
  • Owner: AWS account ID of the topic owner
  • Policy: Access control policy JSON
  • DisplayName: Human-readable name for email protocols
  • SubscriptionsConfirmed: Number of confirmed subscriptions
  • SubscriptionsPending: Number of pending subscriptions
  • SubscriptionsDeleted: Number of deleted subscriptions
  • DeliveryPolicy: Delivery retry policy JSON
  • EffectiveDeliveryPolicy: Currently active delivery policy
  • FifoTopic: Whether this is a FIFO topic ("true" or "false")
  • ContentBasedDeduplication: Whether content-based deduplication is enabled

Usage Example:

const attributes = await client.send(new GetTopicAttributesCommand({
  TopicArn: "arn:aws:sns:us-east-1:123456789012:MyTopic"
}));

console.log("Topic Owner:", attributes.Attributes?.Owner);
console.log("Confirmed Subscriptions:", attributes.Attributes?.SubscriptionsConfirmed);

Set Topic Attributes

Modifies attributes for an existing topic.

/**
 * Sets an attribute for a topic
 * Allows modification of topic configuration
 */
class SetTopicAttributesCommand {
  constructor(input: SetTopicAttributesInput);
}

interface SetTopicAttributesInput {
  /** ARN of the topic */
  TopicArn: string;
  /** Name of the attribute to set */
  AttributeName: string;
  /** Value of the attribute */
  AttributeValue?: string;
}

Usage Examples:

// Set display name
await client.send(new SetTopicAttributesCommand({
  TopicArn: "arn:aws:sns:us-east-1:123456789012:MyTopic",
  AttributeName: "DisplayName",
  AttributeValue: "My Display Name"
}));

// Set delivery policy
await client.send(new SetTopicAttributesCommand({
  TopicArn: "arn:aws:sns:us-east-1:123456789012:MyTopic",
  AttributeName: "DeliveryPolicy",
  AttributeValue: JSON.stringify({
    http: {
      defaultHealthyRetryPolicy: {
        minDelayTarget: 20,
        maxDelayTarget: 20,
        numRetries: 3
      }
    }
  })
}));

// Set topic policy
await client.send(new SetTopicAttributesCommand({
  TopicArn: "arn:aws:sns:us-east-1:123456789012:MyTopic",
  AttributeName: "Policy",
  AttributeValue: JSON.stringify({
    Version: "2012-10-17",
    Statement: [{
      Effect: "Allow",
      Principal: "*",
      Action: "SNS:Publish",
      Resource: "arn:aws:sns:us-east-1:123456789012:MyTopic"
    }]
  })
}));

List Topics

Lists all topics in the account with pagination support.

/**
 * Returns a list of all topics in the account
 * Supports pagination for large numbers of topics
 */
class ListTopicsCommand {
  constructor(input?: ListTopicsInput);
}

interface ListTopicsInput {
  /** Pagination token from previous request */
  NextToken?: string;
}

interface ListTopicsResponse {
  /** Array of topic information */
  Topics?: Topic[];
  /** Token for next page of results */
  NextToken?: string;
}

interface Topic {
  /** ARN of the topic */
  TopicArn?: string;
}

Usage Examples:

// List all topics (first page)
const topicsResult = await client.send(new ListTopicsCommand());
console.log("Topics:", topicsResult.Topics);

// Paginate through all topics  
let nextToken: string | undefined;
do {
  const result = await client.send(new ListTopicsCommand({
    NextToken: nextToken
  }));
  
  result.Topics?.forEach(topic => {
    console.log("Topic ARN:", topic.TopicArn);
  });
  
  nextToken = result.NextToken;
} while (nextToken);

Topic Attributes Reference

Complete reference for topic attribute names and their purposes.

interface TopicAttributeNames {
  /** Topic's Amazon Resource Name */
  TopicArn: string;
  /** AWS account ID that owns the topic */
  Owner: string;
  /** JSON policy document controlling access to the topic */
  Policy: string;
  /** Display name for email protocol notifications */
  DisplayName: string;
  /** Number of confirmed subscriptions */
  SubscriptionsConfirmed: string;
  /** Number of pending subscription confirmations */
  SubscriptionsPending: string;
  /** Number of deleted subscriptions */
  SubscriptionsDeleted: string;
  /** JSON delivery policy for message delivery retries */
  DeliveryPolicy: string;
  /** Currently effective delivery policy */
  EffectiveDeliveryPolicy: string;
  /** Whether topic is FIFO ("true" or "false") */
  FifoTopic: string;
  /** Whether content-based deduplication is enabled */
  ContentBasedDeduplication: string;
  /** KMS key ID for encryption */
  KmsMasterKeyId: string;
  /** Whether server-side encryption is enabled */
  SqsManagedSseEnabled: string;
  /** JSON signature version for message signing */
  SignatureVersion: string;
  /** Whether tracing is enabled for AWS X-Ray */
  TracingConfig: string;
}

Delivery Policy Structure:

interface DeliveryPolicy {
  http?: {
    defaultHealthyRetryPolicy?: {
      minDelayTarget?: number;
      maxDelayTarget?: number;
      numRetries?: number;
      numMaxDelayRetries?: number;
      numMinDelayRetries?: number;
      numNoDelayRetries?: number;
      backoffFunction?: 'linear' | 'arithmetic' | 'geometric' | 'exponential';
    };
    disableSubscriptionOverrides?: boolean;
    defaultThrottlePolicy?: {
      maxReceivesPerMinute?: number;
    };
  };
}

Common Topic Management Patterns

Creating Topic with Full Configuration:

const topicResult = await client.send(new CreateTopicCommand({
  Name: "OrderProcessing.fifo",
  Attributes: {
    DisplayName: "Order Processing Queue",
    FifoTopic: "true",
    ContentBasedDeduplication: "true",
    DeliveryPolicy: JSON.stringify({
      http: {
        defaultHealthyRetryPolicy: {
          minDelayTarget: 20,
          maxDelayTarget: 20,
          numRetries: 3
        }
      }
    }),
    Policy: JSON.stringify({
      Version: "2012-10-17",
      Statement: [{
        Effect: "Allow",
        Principal: { AWS: "arn:aws:iam::123456789012:root" },
        Action: ["SNS:Publish", "SNS:Subscribe"],
        Resource: "*"
      }]
    })
  },
  Tags: [
    { Key: "Environment", Value: "Production" },
    { Key: "Team", Value: "OrderProcessing" },
    { Key: "CostCenter", Value: "Engineering" }
  ]
}));