@ackstate/js-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AckState
+
+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

@@ -0,0 +1,76 @@
+# AckState JavaScript SDK
+
+### **An event is a fact: it exists once received, is seen once delivered, and is done only when acknowledged.**
+
+### Install
+```bash
+npm install @ackstate/js-sdk
+```
+
+### Basic Usage
+
+```javascript
+import { Inbox, LeaseLostError, NetworkError } from "@ackstate/js-sdk";
+
+const inbox = new Inbox({
+  apiKey: process.env.ACK_STATE_API_KEY,
+  projectId: "proj_123",
+  consumerId: "worker-1",
+});
+
+async function run() {
+  while (true) { // or your long running process condition
+
+    const event = await inbox.next();
+    if (!event) break;
+
+    try {
+      // event.body is raw bytes — parse only if you need to
+      const payload = JSON.parse(event.body.toString("utf8"));
+
+      await handleBusinessLogic(payload);
+
+      await inbox.ack(event);
+    } catch (err) {
+      if (err instanceof LeaseLostError) {
+        // Another worker took over. Do nothing.
+        return;
+      }
+
+      if (err instanceof NetworkError) {
+        // Optional: crash or retry at process level
+        throw err;
+      }
+
+      await inbox.fail(event, err instanceof Error ? err.message : undefined);
+    }
+  }
+}
+
+run().catch(console.error);
+```
+
+### Note
+- Each pulled event with `inbox.next()` gets leased for 5 seconds
+- In this lease period, `inbox.ack()` or `inbox.fail()` is expected
+- If the event wasn't acked or failed, it will be eligible to be pulled again  
+
+### Guarantees
+
+- "An event is delivered to only one consumer at a time"
+- "Events are acknowledged only after successful processing"
+- "Failed events are retried safely"
+- "Replay is explicit and intentional"
+- "The SDK never hides state or guesses outcomes"
+
+### What This SDK Does Not Do
+- Retry your business logic
+- Auto-extend leases
+- Parse payloads
+- Hide failures
+- Infer success
+
+### API Reference
+
+For detailed API documentation, see [API_REFERENCE.md](API_REFERENCE.md).
+

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@ackstate/js-sdk",
+  "version": "0.1.0",
+  "description": "Lightweight JavaScript SDK for ackstate event delivery & tracking",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "type": "module",
+  "files": ["src"],
+  "scripts": {},
+  "dependencies": {
+    "undici": "^6.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["ackstate", "events", "webhooks", "ingest", "sdk"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hussam-salah/ackstate-js-sdk.git"
+  },
+  "homepage": "https://github.com/hussam-salah/ackstate-js-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/hussam-salah/ackstate-js-sdk/issues"
+  }
+}

package/src/errors.js

@@ -0,0 +1,5 @@
+export class AuthError extends Error {}
+export class NetworkError extends Error {}
+export class LeaseLostError extends Error {}
+export class StateViolationError extends Error {}
+export class NotFoundError extends Error {}

package/src/event.js

@@ -0,0 +1,5 @@
+export function freezeEvent(event) {
+  Object.freeze(event.headers);
+  Object.freeze(event);
+  return event;
+}

package/src/http.js

@@ -0,0 +1,115 @@
+import { request } from "undici";
+import {
+  AuthError,
+  NetworkError,
+  LeaseLostError,
+  NotFoundError,
+} from "./errors.js";
+
+const API_BASE = "https://api.ackstate.com/v1";
+
+async function handleResponse(res) {
+  if (res.statusCode === 401 || res.statusCode === 403) {
+    throw new AuthError("Invalid API credentials");
+  }
+
+  if (res.statusCode === 404) {
+    throw new NotFoundError("Resource not found");
+  }
+
+  if (res.statusCode === 409) {
+    throw new LeaseLostError("Lease lost");
+  }
+
+  if (res.statusCode >= 400) {
+    throw new NetworkError(`HTTP ${res.statusCode}`);
+  }
+
+  return res;
+}
+
+export async function getNextEvent(apiKey, projectId, consumerId) {
+  try {
+    const params = new URLSearchParams({
+      projectId,
+      consumerId,
+    });
+
+    const res = await request(`${API_BASE}/events/next?${params.toString()}`, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    });
+
+    if (res.statusCode === 204) return null;
+
+    await handleResponse(res);
+
+    const text = await res.body.text();
+    if (!text) return null;
+
+    return JSON.parse(text);
+  } catch (err) {
+    if (err instanceof Error) throw err;
+    throw new NetworkError("Network failure");
+  }
+}
+
+export async function ackEvent(apiKey, consumerId, eventId) {
+  try {
+    const params = new URLSearchParams({
+      consumerId,
+    });
+
+    const res = await request(`${API_BASE}/events/${eventId}/ack?${params.toString()}`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    });
+
+    await handleResponse(res);
+  } catch (err) {
+    if (err instanceof Error) throw err;
+    throw new NetworkError("Network failure");
+  }
+}
+
+export async function failEvent(apiKey, consumerId, eventId, reason) {
+  try {
+    const params = new URLSearchParams({
+      consumerId,
+    });
+
+    const res = await request(`${API_BASE}/events/${eventId}/fail?${params.toString()}`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ reason }),
+    });
+
+    await handleResponse(res);
+  } catch (err) {
+    if (err instanceof Error) throw err;
+    throw new NetworkError("Network failure");
+  }
+}
+
+export async function replayEvent(apiKey, eventId) {
+  try {
+    const res = await request(`${API_BASE}/events/${eventId}/replay`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    });
+
+    await handleResponse(res);
+  } catch (err) {
+    if (err instanceof Error) throw err;
+    throw new NetworkError("Network failure");
+  }
+}

package/src/inbox.js

@@ -0,0 +1,81 @@
+import { freezeEvent } from "./event.js";
+import {
+  getNextEvent,
+  ackEvent,
+  failEvent,
+  replayEvent,
+} from "./http.js";
+import { StateViolationError } from "./errors.js";
+
+export class Inbox {
+  #activeEventIds = new Set();
+  #config;
+
+  constructor(config) {
+    this.#config = config;
+    this.validateConfig(config);
+  }
+
+  async next() {
+    const res = await getNextEvent(
+      this.#config.apiKey,
+      this.#config.projectId,
+      this.#config.consumerId
+    );
+
+    if (!res) return null;
+
+    const event = {
+      id: res.event.id,
+      headers: res.event.headers,
+      body: Buffer.from(res.event.body, "base64"),
+      receivedAt: res.event.received_at,
+      leasedAt: res.event.leased_at,
+      expiresAt: res.event.expires_at,
+    };
+
+    this.#activeEventIds.add(event.id);
+    return freezeEvent(event);
+  }
+
+  async ack(event) {
+    if (!this.#activeEventIds.has(event.id)) {
+      throw new StateViolationError("No active lease for this event");
+    }
+
+    await ackEvent(this.#config.apiKey, this.#config.consumerId, event.id);
+    this.#activeEventIds.delete(event.id);
+  }
+
+  async fail(event, reason) {
+    if (!this.#activeEventIds.has(event.id)) {
+      throw new StateViolationError("No active lease for this event");
+    }
+
+    await failEvent(
+      this.#config.apiKey,
+      this.#config.consumerId,
+      event.id,
+      reason
+    );
+    this.#activeEventIds.delete(event.id);
+  }
+
+  async replay(eventId) {
+    await replayEvent(this.#config.apiKey, eventId);
+  }
+
+  validateConfig(config) {
+    if (!config.apiKey?.trim()) {
+      throw new Error("apiKey is required and cannot be empty");
+    }
+    
+    if (!config.projectId?.trim()) {
+      throw new Error("projectId is required and cannot be empty");
+    }
+    
+    if (!config.consumerId?.trim()) {
+      throw new Error("consumerId is required and cannot be empty");
+    }
+  } 
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { Inbox } from "./inbox.js";
+export * from "./errors.js";