@tratto/email 0.1.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tratto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -51,6 +51,45 @@ const tratto = new Tratto(apiKey, options?);
 
 ---
 
+## Test mode
+
+Every workspace can create **test API keys** (`tratto_test_…`) alongside live ones. A test key runs the exact same pipeline — statuses, email timeline, webhooks — but **nothing is actually delivered**: no domain verification needed, no monthly quota consumed (test sends have their own daily cap).
+
+```ts
+const tratto = new Tratto('tratto_test_...');
+
+// Works immediately, even with an unverified sender domain
+const { id, livemode } = await tratto.emails.send({
+  from: 'Acme <hello@any-domain.dev>',
+  to: 'delivered@simulator.tratto.email',
+  subject: 'Hello from test mode',
+  html: '<p>It works!</p>',
+});
+// livemode === false
+```
+
+### Simulator addresses
+
+The recipient address picks the outcome (any other address simulates a normal delivery):
+
+| Recipient | Outcome |
+|---|---|
+| `delivered@simulator.tratto.email` | `delivered` event |
+| `bounced@simulator.tratto.email` | permanent bounce → email ends `failed` |
+| `soft-bounced@simulator.tratto.email` | transient bounce |
+| `complained@simulator.tratto.email` | spam complaint event |
+
+### What to expect
+
+- Responses and webhook payloads carry `livemode: false` so your integration can tell test traffic apart.
+- A test key only ever sees test data: listing or fetching emails created with a live key returns 404/empty, and vice versa.
+- Test emails are retained for 7 days.
+- Endpoints that reach real recipients (campaign send, template test-send, flow activation) reject test keys with `403 TEST_MODE_NOT_SUPPORTED`.
+
+Switching to production is a one-line change: swap the key for a `tratto_live_…` one (verified sender domain required).
+
+---
+
 ## API Reference
 
 All methods return `Promise<T>`. Use `async/await` or `.then()`.
@@ -276,26 +315,6 @@ const { deletedAt } = await tratto.domains.delete(domain.id);
 
 ---
 
-### API Keys
-
-```ts
-// Create — raw key is shown only once
-const key = await tratto.apiKeys.create({
-  name: 'CI deployment key',
-  env: 'live',
-  permissions: ['emails:send'],
-});
-console.log('Raw key (save this!):', key.key);
-
-// List (prefix only, never raw token)
-const { data } = await tratto.apiKeys.list();
-
-// Revoke
-const { revokedAt } = await tratto.apiKeys.revoke(key.id);
-```
-
----
-
 ### Analytics
 
 ```ts
@@ -422,6 +441,9 @@ See the [`examples/`](examples/) folder:
 | [`campaign.ts`](examples/campaign.ts) | Create, configure, and send a marketing campaign |
 | [`analytics.ts`](examples/analytics.ts) | Fetch delivery metrics and daily timeseries |
 | [`webhook.ts`](examples/webhook.ts) | Register a webhook and inspect delivery history |
+| [`nextjs.ts`](examples/nextjs.ts) | Next.js App Router route handler sending a welcome email |
+| [`express.ts`](examples/express.ts) | Express route sending a password-reset email |
+| [`fastify.ts`](examples/fastify.ts) | Fastify route sending an order-confirmation email via template |
 
 Run any example with [tsx](https://github.com/privatenumber/tsx):
 

package/dist/index.d.mts

@@ -285,29 +285,6 @@ interface ListDomainsParams {
     after?: string;
     limit?: number;
 }
-type ApiKeyEnv = 'live' | 'test';
-interface ApiKey {
-    id: string;
-    name: string;
-    prefix: string;
-    env: ApiKeyEnv;
-    permissions: string[];
-    createdAt: string;
-    lastUsedAt: string | null;
-    revokedAt: string | null;
-}
-interface ApiKeyCreated extends ApiKey {
-    key: string;
-}
-interface CreateApiKeyParams {
-    name: string;
-    env: ApiKeyEnv;
-    permissions: string[];
-}
-interface ListApiKeysParams {
-    after?: string;
-    limit?: number;
-}
 type AnalyticsPeriod = '7d' | '30d' | '90d';
 interface AnalyticsSummary {
     period: AnalyticsPeriod;
@@ -503,15 +480,6 @@ declare class DomainsResource extends BaseResource {
     }>;
 }
 
-declare class ApiKeysResource extends BaseResource {
-    create(params: CreateApiKeyParams, idempotencyKey?: string): Promise<ApiKeyCreated>;
-    list(params?: ListApiKeysParams): Promise<PaginatedResponse<ApiKey>>;
-    revoke(id: string): Promise<{
-        id: string;
-        revokedAt: string;
-    }>;
-}
-
 declare class AnalyticsResource extends BaseResource {
     getSummary(period?: AnalyticsPeriod): Promise<AnalyticsSummary>;
     getTimeseries(period?: AnalyticsPeriod): Promise<TimeseriesPoint[]>;
@@ -552,11 +520,10 @@ declare class Tratto {
     readonly templates: TemplatesResource;
     readonly webhooks: WebhooksResource;
     readonly domains: DomainsResource;
-    readonly apiKeys: ApiKeysResource;
     readonly analytics: AnalyticsResource;
     readonly flows: FlowsResource;
     readonly workspace: WorkspaceResource;
     constructor(apiKey: string, options?: TrattoOptions);
 }
 
-export { type AddContactsToAudienceResult, type AnalyticsPeriod, type AnalyticsSummary, type ApiKey, type ApiKeyCreated, type ApiKeyEnv, type Audience, type AudienceRule, type AudienceRuleOperator, type Campaign, type CampaignStats, type CampaignStatsDetail, type CampaignStatus, type Contact, type ContactStatus, type CreateApiKeyParams, type CreateAudienceParams, type CreateCampaignParams, type CreateContactParams, type CreateFlowParams, type CreateTemplateParams, type CreateWebhookParams, type Domain, type DomainRecord, type DomainStatus, type DomainSummary, type EmailDetail, type EmailEvent, type EmailSummary, type Flow, type FlowStatus, type FlowStep, type FlowStepType, type FlowTrigger, type FlowTriggerType, type ImportJobStatus, type InviteMemberParams, type ListApiKeysParams, type ListAudiencesParams, type ListCampaignsParams, type ListContactsParams, type ListDomainsParams, type ListEmailsParams, type ListFlowsParams, type ListTemplatesParams, type ListWebhookDeliveriesParams, type PaginatedResponse, type Pagination, type SendCampaignParams, type SendEmailParams, type Template, type TemplateStatus, type TemplateSummary, type TemplateVersion, type TemplateVersionSummary, type TimeseriesPoint, Tratto, TrattoError, type TrattoOptions, type UpdateContactParams, type UpdateFlowParams, type UpdateMemberParams, type UpdateTemplateParams, type UpdateWorkspaceParams, type UpdateWorkspacePreferencesParams, type Webhook, type WebhookDelivery, type WebhookDeliveryStatus, type WebhookEventType, type WebhookStatus, type Workspace, type WorkspaceLocale, type WorkspaceMember, type WorkspaceMemberRole, type WorkspacePlan, type WorkspacePreferences };
+export { type AddContactsToAudienceResult, type AnalyticsPeriod, type AnalyticsSummary, type Audience, type AudienceRule, type AudienceRuleOperator, type Campaign, type CampaignStats, type CampaignStatsDetail, type CampaignStatus, type Contact, type ContactStatus, type CreateAudienceParams, type CreateCampaignParams, type CreateContactParams, type CreateFlowParams, type CreateTemplateParams, type CreateWebhookParams, type Domain, type DomainRecord, type DomainStatus, type DomainSummary, type EmailDetail, type EmailEvent, type EmailSummary, type Flow, type FlowStatus, type FlowStep, type FlowStepType, type FlowTrigger, type FlowTriggerType, type ImportJobStatus, type InviteMemberParams, type ListAudiencesParams, type ListCampaignsParams, type ListContactsParams, type ListDomainsParams, type ListEmailsParams, type ListFlowsParams, type ListTemplatesParams, type ListWebhookDeliveriesParams, type PaginatedResponse, type Pagination, type SendCampaignParams, type SendEmailParams, type Template, type TemplateStatus, type TemplateSummary, type TemplateVersion, type TemplateVersionSummary, type TimeseriesPoint, Tratto, TrattoError, type TrattoOptions, type UpdateContactParams, type UpdateFlowParams, type UpdateMemberParams, type UpdateTemplateParams, type UpdateWorkspaceParams, type UpdateWorkspacePreferencesParams, type Webhook, type WebhookDelivery, type WebhookDeliveryStatus, type WebhookEventType, type WebhookStatus, type Workspace, type WorkspaceLocale, type WorkspaceMember, type WorkspaceMemberRole, type WorkspacePlan, type WorkspacePreferences };

package/dist/index.d.ts

@@ -285,29 +285,6 @@ interface ListDomainsParams {
     after?: string;
     limit?: number;
 }
-type ApiKeyEnv = 'live' | 'test';
-interface ApiKey {
-    id: string;
-    name: string;
-    prefix: string;
-    env: ApiKeyEnv;
-    permissions: string[];
-    createdAt: string;
-    lastUsedAt: string | null;
-    revokedAt: string | null;
-}
-interface ApiKeyCreated extends ApiKey {
-    key: string;
-}
-interface CreateApiKeyParams {
-    name: string;
-    env: ApiKeyEnv;
-    permissions: string[];
-}
-interface ListApiKeysParams {
-    after?: string;
-    limit?: number;
-}
 type AnalyticsPeriod = '7d' | '30d' | '90d';
 interface AnalyticsSummary {
     period: AnalyticsPeriod;
@@ -503,15 +480,6 @@ declare class DomainsResource extends BaseResource {
     }>;
 }
 
-declare class ApiKeysResource extends BaseResource {
-    create(params: CreateApiKeyParams, idempotencyKey?: string): Promise<ApiKeyCreated>;
-    list(params?: ListApiKeysParams): Promise<PaginatedResponse<ApiKey>>;
-    revoke(id: string): Promise<{
-        id: string;
-        revokedAt: string;
-    }>;
-}
-
 declare class AnalyticsResource extends BaseResource {
     getSummary(period?: AnalyticsPeriod): Promise<AnalyticsSummary>;
     getTimeseries(period?: AnalyticsPeriod): Promise<TimeseriesPoint[]>;
@@ -552,11 +520,10 @@ declare class Tratto {
     readonly templates: TemplatesResource;
     readonly webhooks: WebhooksResource;
     readonly domains: DomainsResource;
-    readonly apiKeys: ApiKeysResource;
     readonly analytics: AnalyticsResource;
     readonly flows: FlowsResource;
     readonly workspace: WorkspaceResource;
     constructor(apiKey: string, options?: TrattoOptions);
 }
 
-export { type AddContactsToAudienceResult, type AnalyticsPeriod, type AnalyticsSummary, type ApiKey, type ApiKeyCreated, type ApiKeyEnv, type Audience, type AudienceRule, type AudienceRuleOperator, type Campaign, type CampaignStats, type CampaignStatsDetail, type CampaignStatus, type Contact, type ContactStatus, type CreateApiKeyParams, type CreateAudienceParams, type CreateCampaignParams, type CreateContactParams, type CreateFlowParams, type CreateTemplateParams, type CreateWebhookParams, type Domain, type DomainRecord, type DomainStatus, type DomainSummary, type EmailDetail, type EmailEvent, type EmailSummary, type Flow, type FlowStatus, type FlowStep, type FlowStepType, type FlowTrigger, type FlowTriggerType, type ImportJobStatus, type InviteMemberParams, type ListApiKeysParams, type ListAudiencesParams, type ListCampaignsParams, type ListContactsParams, type ListDomainsParams, type ListEmailsParams, type ListFlowsParams, type ListTemplatesParams, type ListWebhookDeliveriesParams, type PaginatedResponse, type Pagination, type SendCampaignParams, type SendEmailParams, type Template, type TemplateStatus, type TemplateSummary, type TemplateVersion, type TemplateVersionSummary, type TimeseriesPoint, Tratto, TrattoError, type TrattoOptions, type UpdateContactParams, type UpdateFlowParams, type UpdateMemberParams, type UpdateTemplateParams, type UpdateWorkspaceParams, type UpdateWorkspacePreferencesParams, type Webhook, type WebhookDelivery, type WebhookDeliveryStatus, type WebhookEventType, type WebhookStatus, type Workspace, type WorkspaceLocale, type WorkspaceMember, type WorkspaceMemberRole, type WorkspacePlan, type WorkspacePreferences };
+export { type AddContactsToAudienceResult, type AnalyticsPeriod, type AnalyticsSummary, type Audience, type AudienceRule, type AudienceRuleOperator, type Campaign, type CampaignStats, type CampaignStatsDetail, type CampaignStatus, type Contact, type ContactStatus, type CreateAudienceParams, type CreateCampaignParams, type CreateContactParams, type CreateFlowParams, type CreateTemplateParams, type CreateWebhookParams, type Domain, type DomainRecord, type DomainStatus, type DomainSummary, type EmailDetail, type EmailEvent, type EmailSummary, type Flow, type FlowStatus, type FlowStep, type FlowStepType, type FlowTrigger, type FlowTriggerType, type ImportJobStatus, type InviteMemberParams, type ListAudiencesParams, type ListCampaignsParams, type ListContactsParams, type ListDomainsParams, type ListEmailsParams, type ListFlowsParams, type ListTemplatesParams, type ListWebhookDeliveriesParams, type PaginatedResponse, type Pagination, type SendCampaignParams, type SendEmailParams, type Template, type TemplateStatus, type TemplateSummary, type TemplateVersion, type TemplateVersionSummary, type TimeseriesPoint, Tratto, TrattoError, type TrattoOptions, type UpdateContactParams, type UpdateFlowParams, type UpdateMemberParams, type UpdateTemplateParams, type UpdateWorkspaceParams, type UpdateWorkspacePreferencesParams, type Webhook, type WebhookDelivery, type WebhookDeliveryStatus, type WebhookEventType, type WebhookStatus, type Workspace, type WorkspaceLocale, type WorkspaceMember, type WorkspaceMemberRole, type WorkspacePlan, type WorkspacePreferences };

package/dist/index.js

@@ -288,23 +288,6 @@ var DomainsResource = class extends BaseResource {
   }
 };
 
-// src/resources/api-keys.ts
-var ApiKeysResource = class extends BaseResource {
-  create(params, idempotencyKey) {
-    return this.fetchData("POST", "/v1/api-keys", {
-      body: params,
-      headers: idempotencyKey ? { "Idempotency-Key": idempotencyKey } : void 0
-    });
-  }
-  list(params) {
-    const qs = this.buildQuery({ after: params?.after, limit: params?.limit });
-    return this.fetch("GET", `/v1/api-keys${qs}`);
-  }
-  revoke(id) {
-    return this.fetchData("DELETE", `/v1/api-keys/${id}`);
-  }
-};
-
 // src/resources/analytics.ts
 var AnalyticsResource = class extends BaseResource {
   getSummary(period = "30d") {
@@ -390,7 +373,6 @@ var Tratto = class {
     this.templates = new TemplatesResource(apiKey, baseUrl);
     this.webhooks = new WebhooksResource(apiKey, baseUrl);
     this.domains = new DomainsResource(apiKey, baseUrl);
-    this.apiKeys = new ApiKeysResource(apiKey, baseUrl);
     this.analytics = new AnalyticsResource(apiKey, baseUrl);
     this.flows = new FlowsResource(apiKey, baseUrl);
     this.workspace = new WorkspaceResource(apiKey, baseUrl);

package/dist/index.mjs

@@ -261,23 +261,6 @@ var DomainsResource = class extends BaseResource {
   }
 };
 
-// src/resources/api-keys.ts
-var ApiKeysResource = class extends BaseResource {
-  create(params, idempotencyKey) {
-    return this.fetchData("POST", "/v1/api-keys", {
-      body: params,
-      headers: idempotencyKey ? { "Idempotency-Key": idempotencyKey } : void 0
-    });
-  }
-  list(params) {
-    const qs = this.buildQuery({ after: params?.after, limit: params?.limit });
-    return this.fetch("GET", `/v1/api-keys${qs}`);
-  }
-  revoke(id) {
-    return this.fetchData("DELETE", `/v1/api-keys/${id}`);
-  }
-};
-
 // src/resources/analytics.ts
 var AnalyticsResource = class extends BaseResource {
   getSummary(period = "30d") {
@@ -363,7 +346,6 @@ var Tratto = class {
     this.templates = new TemplatesResource(apiKey, baseUrl);
     this.webhooks = new WebhooksResource(apiKey, baseUrl);
     this.domains = new DomainsResource(apiKey, baseUrl);
-    this.apiKeys = new ApiKeysResource(apiKey, baseUrl);
     this.analytics = new AnalyticsResource(apiKey, baseUrl);
     this.flows = new FlowsResource(apiKey, baseUrl);
     this.workspace = new WorkspaceResource(apiKey, baseUrl);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tratto/email",
-  "version": "0.1.0",
-  "description": "Tratto Node.js SDK — send transactional and marketing email",
+  "version": "1.0.0",
+  "description": "Tratto Node.js SDK \u2014 send transactional and marketing email",
   "author": "Tratto <hello@tratto.email>",
   "license": "MIT",
   "homepage": "https://tratto.email",
@@ -22,7 +22,9 @@
       "require": "./dist/index.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "sideEffects": false,
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
@@ -30,12 +32,17 @@
     "lint": "eslint src --ext .ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "devDependencies": {
+    "@types/express": "^5.0.0",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
     "eslint": "^9.0.0",
+    "express": "^5.0.0",
+    "fastify": "^5.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"