@topmail/sdk 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,141 @@
+# @topmail/sdk
+
+Official TypeScript SDK for the [TopMail](https://topmail.so) API.
+
+## Install
+
+```bash
+npm install @topmail/sdk
+```
+
+## Quick Start
+
+```typescript
+import { TopMail } from '@topmail/sdk';
+
+const topmail = new TopMail('tm_live_your_api_key');
+
+// Send an email
+await topmail.email.send({
+  from_email: 'you@example.com',
+  to: 'recipient@example.com',
+  subject: 'Hello from TopMail',
+  html: '<h1>Welcome!</h1>',
+});
+```
+
+## Resources
+
+| Resource | Methods |
+|----------|---------|
+| `topmail.contacts` | `list` `get` `create` `update` `delete` |
+| `topmail.lists` | `list` `get` `create` `update` `delete` |
+| `topmail.lists.members` | `list` `add` `remove` |
+| `topmail.email` | `send` `batch` `batchStatus` `messageStatus` |
+| `topmail.campaigns` | `list` |
+| `topmail.templates` | `list` |
+| `topmail.tags` | `list` `get` `create` `update` `delete` |
+| `topmail.tags.contacts` | `list` `add` `remove` |
+| `topmail.segments` | `list` `get` `create` `update` `delete` `contacts` `estimate` |
+| `topmail.automations` | `list` `get` `create` `update` `delete` `trigger` |
+| `topmail.automations.steps` | `list` `get` `create` `update` `delete` |
+| `topmail.automations.runs` | `list` `cancel` |
+| `topmail.domains` | `list` `get` `create` `delete` `verify` |
+| `topmail.suppressions` | `list` `add` `remove` |
+| `topmail.webhooks` | `list` `create` `delete` |
+| `topmail.tracking` | `productView` |
+| `topmail.conversions` | `create` |
+| `topmail.health` | `check` |
+
+## Examples
+
+### Contacts
+
+```typescript
+// List contacts
+const { data, pagination } = await topmail.contacts.list({ limit: 50 });
+
+// Create a contact
+const { data: contact } = await topmail.contacts.create({
+  email: 'jane@example.com',
+  first_name: 'Jane',
+  last_name: 'Doe',
+});
+
+// Update a contact
+await topmail.contacts.update(contact.id, {
+  first_name: 'Janet',
+});
+```
+
+### Lists
+
+```typescript
+// Create a list
+const { data: list } = await topmail.lists.create({
+  name: 'Newsletter Subscribers',
+});
+
+// Add contacts to a list
+await topmail.lists.members.add(list.id, [contact.id]);
+```
+
+### Tags
+
+```typescript
+// Create and apply a tag
+const { data: tag } = await topmail.tags.create({ name: 'VIP' });
+await topmail.tags.contacts.add(tag.id, [contact.id]);
+```
+
+### Automations
+
+```typescript
+// Trigger an automation
+await topmail.automations.trigger(automationId, {
+  contact_id: contact.id,
+});
+```
+
+## Sandbox Mode
+
+API keys starting with `tm_test_` activate sandbox mode. Check with:
+
+```typescript
+const topmail = new TopMail('tm_test_your_key');
+console.log(topmail.isSandbox); // true
+```
+
+## Error Handling
+
+```typescript
+import { TopMail, TopMailError, RateLimitError } from '@topmail/sdk';
+
+try {
+  await topmail.contacts.get('nonexistent');
+} catch (err) {
+  if (err instanceof RateLimitError) {
+    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
+  } else if (err instanceof TopMailError) {
+    console.log(err.message, err.code, err.statusCode);
+  }
+}
+```
+
+Error classes: `TopMailError`, `ValidationError`, `AuthenticationError`, `ForbiddenError`, `NotFoundError`, `RateLimitError`, `ServerError`.
+
+## Configuration
+
+```typescript
+const topmail = new TopMail('tm_live_key', {
+  baseUrl: 'https://api.topmail.so/api', // default
+});
+```
+
+## Requirements
+
+- Node.js >= 18
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topmail/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Official TypeScript SDK for the TopMail API",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -45,6 +45,9 @@
     "typescript": "^5.4.0",
     "vitest": "^2.0.0"
   },
-  "files": ["dist"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "license": "MIT"
 }