fakecloud 0.5.0

package/README.md

@@ -0,0 +1,143 @@
+# fakecloud
+
+TypeScript client SDK for [fakecloud](https://github.com/faiscadev/fakecloud) — a local AWS cloud emulator.
+
+Provides typed access to the fakecloud introspection and simulation API (`/_fakecloud/*` endpoints), letting you inspect emulator state and trigger time-based processors in tests.
+
+## Installation
+
+```bash
+npm install fakecloud
+```
+
+## Quick start
+
+```typescript
+import { FakeCloud } from "fakecloud";
+
+const fc = new FakeCloud("http://localhost:4566");
+
+// Check server health
+const health = await fc.health();
+console.log(health.version, health.services);
+
+// Reset all state between tests
+await fc.reset();
+
+// Inspect SES emails sent during a test
+const { emails } = await fc.ses.getEmails();
+console.log(`Sent ${emails.length} emails`);
+
+// Inspect SNS messages
+const { messages } = await fc.sns.getMessages();
+
+// Inspect SQS messages across all queues
+const { queues } = await fc.sqs.getMessages();
+
+// Advance DynamoDB TTL processor
+const { expiredItems } = await fc.dynamodb.tickTtl();
+
+// Advance S3 lifecycle processor
+const { expiredObjects } = await fc.s3.tickLifecycle();
+```
+
+## API reference
+
+### `FakeCloud`
+
+```typescript
+const fc = new FakeCloud(baseUrl?: string);
+```
+
+Top-level client. Defaults to `http://localhost:4566`.
+
+| Method                  | Description             |
+| ----------------------- | ----------------------- |
+| `health()`              | Server health check     |
+| `reset()`               | Reset all service state |
+| `resetService(service)` | Reset a single service  |
+
+### `fc.lambda`
+
+| Method                         | Description                          |
+| ------------------------------ | ------------------------------------ |
+| `getInvocations()`             | List recorded Lambda invocations     |
+| `getWarmContainers()`          | List warm (cached) Lambda containers |
+| `evictContainer(functionName)` | Evict a warm container               |
+
+### `fc.ses`
+
+| Method                 | Description                               |
+| ---------------------- | ----------------------------------------- |
+| `getEmails()`          | List all sent emails                      |
+| `simulateInbound(req)` | Simulate an inbound email (receipt rules) |
+
+### `fc.sns`
+
+| Method                      | Description                             |
+| --------------------------- | --------------------------------------- |
+| `getMessages()`             | List all published messages             |
+| `getPendingConfirmations()` | List subscriptions pending confirmation |
+| `confirmSubscription(req)`  | Confirm a pending subscription          |
+
+### `fc.sqs`
+
+| Method                | Description                           |
+| --------------------- | ------------------------------------- |
+| `getMessages()`       | List all messages across all queues   |
+| `tickExpiration()`    | Tick the message expiration processor |
+| `forceDlq(queueName)` | Force all messages to the queue's DLQ |
+
+### `fc.events`
+
+| Method          | Description                            |
+| --------------- | -------------------------------------- |
+| `getHistory()`  | Get event history and delivery records |
+| `fireRule(req)` | Fire an EventBridge rule manually      |
+
+### `fc.s3`
+
+| Method               | Description                  |
+| -------------------- | ---------------------------- |
+| `getNotifications()` | List S3 notification events  |
+| `tickLifecycle()`    | Tick the lifecycle processor |
+
+### `fc.dynamodb`
+
+| Method      | Description            |
+| ----------- | ---------------------- |
+| `tickTtl()` | Tick the TTL processor |
+
+### `fc.secretsmanager`
+
+| Method           | Description                 |
+| ---------------- | --------------------------- |
+| `tickRotation()` | Tick the rotation scheduler |
+
+### `fc.cognito`
+
+| Method                           | Description                          |
+| -------------------------------- | ------------------------------------ |
+| `getUserCodes(poolId, username)` | Get confirmation codes for a user    |
+| `getConfirmationCodes()`         | List all confirmation codes          |
+| `confirmUser(req)`               | Confirm a user (bypass verification) |
+| `getTokens()`                    | List all active tokens               |
+| `expireTokens(req)`              | Expire tokens (optionally filtered)  |
+| `getAuthEvents()`                | List auth events                     |
+
+### Error handling
+
+All methods throw `FakeCloudError` on non-2xx responses:
+
+```typescript
+import { FakeCloudError } from "fakecloud";
+
+try {
+  await fc.cognito.confirmUser({ userPoolId: "pool-1", username: "nobody" });
+} catch (err) {
+  if (err instanceof FakeCloudError) {
+    console.log(err.status); // 404
+    console.log(err.body); // "user not found"
+  }
+}
+```

package/dist/client.d.ts

@@ -0,0 +1,90 @@
+import type { HealthResponse, ResetResponse, ResetServiceResponse, LambdaInvocationsResponse, WarmContainersResponse, EvictContainerResponse, SesEmailsResponse, InboundEmailRequest, InboundEmailResponse, SnsMessagesResponse, PendingConfirmationsResponse, ConfirmSubscriptionRequest, ConfirmSubscriptionResponse, SqsMessagesResponse, ExpirationTickResponse, ForceDlqResponse, EventHistoryResponse, FireRuleRequest, FireRuleResponse, S3NotificationsResponse, LifecycleTickResponse, TtlTickResponse, RotationTickResponse, UserConfirmationCodes, ConfirmationCodesResponse, ConfirmUserRequest, ConfirmUserResponse, TokensResponse, ExpireTokensRequest, ExpireTokensResponse, AuthEventsResponse } from "./types.js";
+export declare class FakeCloudError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+export declare class LambdaClient {
+    private baseUrl;
+    constructor(baseUrl: string);
+    getInvocations(): Promise<LambdaInvocationsResponse>;
+    getWarmContainers(): Promise<WarmContainersResponse>;
+    evictContainer(functionName: string): Promise<EvictContainerResponse>;
+}
+export declare class SesClient {
+    private baseUrl;
+    constructor(baseUrl: string);
+    getEmails(): Promise<SesEmailsResponse>;
+    simulateInbound(req: InboundEmailRequest): Promise<InboundEmailResponse>;
+}
+export declare class SnsClient {
+    private baseUrl;
+    constructor(baseUrl: string);
+    getMessages(): Promise<SnsMessagesResponse>;
+    getPendingConfirmations(): Promise<PendingConfirmationsResponse>;
+    confirmSubscription(req: ConfirmSubscriptionRequest): Promise<ConfirmSubscriptionResponse>;
+}
+export declare class SqsClient {
+    private baseUrl;
+    constructor(baseUrl: string);
+    getMessages(): Promise<SqsMessagesResponse>;
+    tickExpiration(): Promise<ExpirationTickResponse>;
+    forceDlq(queueName: string): Promise<ForceDlqResponse>;
+}
+export declare class EventsClient {
+    private baseUrl;
+    constructor(baseUrl: string);
+    getHistory(): Promise<EventHistoryResponse>;
+    fireRule(req: FireRuleRequest): Promise<FireRuleResponse>;
+}
+export declare class S3Client {
+    private baseUrl;
+    constructor(baseUrl: string);
+    getNotifications(): Promise<S3NotificationsResponse>;
+    tickLifecycle(): Promise<LifecycleTickResponse>;
+}
+export declare class DynamoDbClient {
+    private baseUrl;
+    constructor(baseUrl: string);
+    tickTtl(): Promise<TtlTickResponse>;
+}
+export declare class SecretsManagerClient {
+    private baseUrl;
+    constructor(baseUrl: string);
+    tickRotation(): Promise<RotationTickResponse>;
+}
+export declare class CognitoClient {
+    private baseUrl;
+    constructor(baseUrl: string);
+    getUserCodes(poolId: string, username: string): Promise<UserConfirmationCodes>;
+    getConfirmationCodes(): Promise<ConfirmationCodesResponse>;
+    confirmUser(req: ConfirmUserRequest): Promise<ConfirmUserResponse>;
+    getTokens(): Promise<TokensResponse>;
+    expireTokens(req: ExpireTokensRequest): Promise<ExpireTokensResponse>;
+    getAuthEvents(): Promise<AuthEventsResponse>;
+}
+export declare class FakeCloud {
+    private readonly baseUrl;
+    private readonly _lambda;
+    private readonly _ses;
+    private readonly _sns;
+    private readonly _sqs;
+    private readonly _events;
+    private readonly _s3;
+    private readonly _dynamodb;
+    private readonly _secretsmanager;
+    private readonly _cognito;
+    constructor(baseUrl?: string);
+    health(): Promise<HealthResponse>;
+    reset(): Promise<ResetResponse>;
+    resetService(service: string): Promise<ResetServiceResponse>;
+    get lambda(): LambdaClient;
+    get ses(): SesClient;
+    get sns(): SnsClient;
+    get sqs(): SqsClient;
+    get events(): EventsClient;
+    get s3(): S3Client;
+    get dynamodb(): DynamoDbClient;
+    get secretsmanager(): SecretsManagerClient;
+    get cognito(): CognitoClient;
+}

package/dist/client.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FakeCloud = exports.CognitoClient = exports.SecretsManagerClient = exports.DynamoDbClient = exports.S3Client = exports.EventsClient = exports.SqsClient = exports.SnsClient = exports.SesClient = exports.LambdaClient = exports.FakeCloudError = void 0;
+class FakeCloudError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`fakecloud API error (${status}): ${body}`);
+        this.status = status;
+        this.body = body;
+        this.name = "FakeCloudError";
+    }
+}
+exports.FakeCloudError = FakeCloudError;
+async function parse(resp) {
+    if (!resp.ok) {
+        const body = await resp.text().catch(() => "");
+        throw new FakeCloudError(resp.status, body);
+    }
+    return resp.json();
+}
+// ── Sub-clients ────────────────────────────────────────────────────
+class LambdaClient {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    async getInvocations() {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/lambda/invocations`);
+        return parse(resp);
+    }
+    async getWarmContainers() {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/lambda/warm-containers`);
+        return parse(resp);
+    }
+    async evictContainer(functionName) {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/lambda/${encodeURIComponent(functionName)}/evict-container`, { method: "POST" });
+        return parse(resp);
+    }
+}
+exports.LambdaClient = LambdaClient;
+class SesClient {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    async getEmails() {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/ses/emails`);
+        return parse(resp);
+    }
+    async simulateInbound(req) {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/ses/inbound`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(req),
+        });
+        return parse(resp);
+    }
+}
+exports.SesClient = SesClient;
+class SnsClient {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    async getMessages() {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/sns/messages`);
+        return parse(resp);
+    }
+    async getPendingConfirmations() {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/sns/pending-confirmations`);
+        return parse(resp);
+    }
+    async confirmSubscription(req) {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/sns/confirm-subscription`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(req),
+        });
+        return parse(resp);
+    }
+}
+exports.SnsClient = SnsClient;
+class SqsClient {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    async getMessages() {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/sqs/messages`);
+        return parse(resp);
+    }
+    async tickExpiration() {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/sqs/expiration-processor/tick`, { method: "POST" });
+        return parse(resp);
+    }
+    async forceDlq(queueName) {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/sqs/${encodeURIComponent(queueName)}/force-dlq`, { method: "POST" });
+        return parse(resp);
+    }
+}
+exports.SqsClient = SqsClient;
+class EventsClient {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    async getHistory() {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/events/history`);
+        return parse(resp);
+    }
+    async fireRule(req) {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/events/fire-rule`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(req),
+        });
+        return parse(resp);
+    }
+}
+exports.EventsClient = EventsClient;
+class S3Client {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    async getNotifications() {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/s3/notifications`);
+        return parse(resp);
+    }
+    async tickLifecycle() {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/s3/lifecycle-processor/tick`, { method: "POST" });
+        return parse(resp);
+    }
+}
+exports.S3Client = S3Client;
+class DynamoDbClient {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    async tickTtl() {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/dynamodb/ttl-processor/tick`, { method: "POST" });
+        return parse(resp);
+    }
+}
+exports.DynamoDbClient = DynamoDbClient;
+class SecretsManagerClient {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    async tickRotation() {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/secretsmanager/rotation-scheduler/tick`, { method: "POST" });
+        return parse(resp);
+    }
+}
+exports.SecretsManagerClient = SecretsManagerClient;
+class CognitoClient {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    async getUserCodes(poolId, username) {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/cognito/confirmation-codes/${encodeURIComponent(poolId)}/${encodeURIComponent(username)}`);
+        return parse(resp);
+    }
+    async getConfirmationCodes() {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/cognito/confirmation-codes`);
+        return parse(resp);
+    }
+    async confirmUser(req) {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/cognito/confirm-user`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(req),
+        });
+        // This endpoint returns 404 for missing users but still has a JSON body
+        if (resp.status === 404) {
+            const body = await resp.json();
+            throw new FakeCloudError(404, body.error ?? "user not found");
+        }
+        return parse(resp);
+    }
+    async getTokens() {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/cognito/tokens`);
+        return parse(resp);
+    }
+    async expireTokens(req) {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/cognito/expire-tokens`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(req),
+        });
+        return parse(resp);
+    }
+    async getAuthEvents() {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/cognito/auth-events`);
+        return parse(resp);
+    }
+}
+exports.CognitoClient = CognitoClient;
+// ── Main client ────────────────────────────────────────────────────
+class FakeCloud {
+    baseUrl;
+    _lambda;
+    _ses;
+    _sns;
+    _sqs;
+    _events;
+    _s3;
+    _dynamodb;
+    _secretsmanager;
+    _cognito;
+    constructor(baseUrl = "http://localhost:4566") {
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this._lambda = new LambdaClient(this.baseUrl);
+        this._ses = new SesClient(this.baseUrl);
+        this._sns = new SnsClient(this.baseUrl);
+        this._sqs = new SqsClient(this.baseUrl);
+        this._events = new EventsClient(this.baseUrl);
+        this._s3 = new S3Client(this.baseUrl);
+        this._dynamodb = new DynamoDbClient(this.baseUrl);
+        this._secretsmanager = new SecretsManagerClient(this.baseUrl);
+        this._cognito = new CognitoClient(this.baseUrl);
+    }
+    // ── Health & Reset ─────────────────────────────────────────────
+    async health() {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/health`);
+        return parse(resp);
+    }
+    async reset() {
+        const resp = await fetch(`${this.baseUrl}/_reset`, { method: "POST" });
+        return parse(resp);
+    }
+    async resetService(service) {
+        const resp = await fetch(`${this.baseUrl}/_fakecloud/reset/${encodeURIComponent(service)}`, { method: "POST" });
+        return parse(resp);
+    }
+    // ── Sub-clients ────────────────────────────────────────────────
+    get lambda() {
+        return this._lambda;
+    }
+    get ses() {
+        return this._ses;
+    }
+    get sns() {
+        return this._sns;
+    }
+    get sqs() {
+        return this._sqs;
+    }
+    get events() {
+        return this._events;
+    }
+    get s3() {
+        return this._s3;
+    }
+    get dynamodb() {
+        return this._dynamodb;
+    }
+    get secretsmanager() {
+        return this._secretsmanager;
+    }
+    get cognito() {
+        return this._cognito;
+    }
+}
+exports.FakeCloud = FakeCloud;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { FakeCloud, FakeCloudError } from "./client.js";
+export { LambdaClient, SesClient, SnsClient, SqsClient, EventsClient, S3Client, DynamoDbClient, SecretsManagerClient, CognitoClient, } from "./client.js";
+export type * from "./types.js";

package/dist/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CognitoClient = exports.SecretsManagerClient = exports.DynamoDbClient = exports.S3Client = exports.EventsClient = exports.SqsClient = exports.SnsClient = exports.SesClient = exports.LambdaClient = exports.FakeCloudError = exports.FakeCloud = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "FakeCloud", { enumerable: true, get: function () { return client_js_1.FakeCloud; } });
+Object.defineProperty(exports, "FakeCloudError", { enumerable: true, get: function () { return client_js_1.FakeCloudError; } });
+var client_js_2 = require("./client.js");
+Object.defineProperty(exports, "LambdaClient", { enumerable: true, get: function () { return client_js_2.LambdaClient; } });
+Object.defineProperty(exports, "SesClient", { enumerable: true, get: function () { return client_js_2.SesClient; } });
+Object.defineProperty(exports, "SnsClient", { enumerable: true, get: function () { return client_js_2.SnsClient; } });
+Object.defineProperty(exports, "SqsClient", { enumerable: true, get: function () { return client_js_2.SqsClient; } });
+Object.defineProperty(exports, "EventsClient", { enumerable: true, get: function () { return client_js_2.EventsClient; } });
+Object.defineProperty(exports, "S3Client", { enumerable: true, get: function () { return client_js_2.S3Client; } });
+Object.defineProperty(exports, "DynamoDbClient", { enumerable: true, get: function () { return client_js_2.DynamoDbClient; } });
+Object.defineProperty(exports, "SecretsManagerClient", { enumerable: true, get: function () { return client_js_2.SecretsManagerClient; } });
+Object.defineProperty(exports, "CognitoClient", { enumerable: true, get: function () { return client_js_2.CognitoClient; } });