@semiotic-labs/agentium-sdk 0.1.0 → 0.2.1

package/README.md

@@ -1 +1,117 @@
-# agentium-sdk
+<!--
+SPDX-FileCopyrightText: 2025 Semiotic AI, Inc.
+
+SPDX-License-Identifier: MIT
+-->
+
+# @semiotic-labs/agentium-sdk
+
+A TypeScript SDK to simplify interaction with the `/v1/identity/connect` API endpoint.
+
+## Installation
+
+Install the package using npm:
+
+```bash
+npm install @semiotic-labs/agentium-sdk
+```
+
+## Usage
+
+### Basic Usage
+
+To connect to the default production API:
+
+```typescript
+import { AgentiumClient } from '@semiotic-labs/agentium-sdk';
+
+const client = new AgentiumClient();
+
+async function connectIdentity() {
+  try {
+    const googleToken = 'YOUR_GOOGLE_JWT'; // Replace with your actual Google JWT
+    const response = await client.connectGoogleIdentity(googleToken);
+    console.log('Connected Identity:', response);
+  } catch (error) {
+    console.error('Failed to connect identity:', error);
+  }
+}
+
+connectIdentity();
+```
+
+### Advanced Usage: Custom Endpoint
+
+You can specify a custom `baseURL` in the constructor, which is useful for testing against local or staging environments.
+
+```typescript
+import { AgentiumClient } from '@semiotic-labs/agentium-sdk';
+
+// Example for a local development server
+const localClient = new AgentiumClient({
+  baseURL: 'http://localhost:8080',
+});
+
+async function connectIdentityLocal() {
+  try {
+    const googleToken = 'YOUR_GOOGLE_JWT';
+    const response = await localClient.connectGoogleIdentity(googleToken);
+    console.log('Connected Identity (Local):', response);
+  } catch (error) {
+    console.error('Failed to connect identity (Local):', error);
+  }
+}
+
+connectIdentityLocal();
+```
+
+## For Developers
+
+### Project Setup
+
+1.  Clone the repository.
+2.  Install dependencies:
+    ```bash
+    npm install
+    ```
+
+### REUSE Compliance
+
+This project follows the [REUSE Specification](https://reuse.software/spec/). To ensure compliance:
+
+1.  **Install REUSE Tool:** You'll need to install the `reuse` command-line tool globally via `pip`:
+    ```bash
+    pip install reuse
+    ```
+
+### Applying SPDX Headers
+
+To add or update SPDX license and copyright headers to all relevant files:
+
+```bash
+npm run reuse:write
+```
+
+### Verify Compliance
+
+To check if the project is fully REUSE compliant:
+
+```bash
+npm run reuse:check
+```
+
+### Running Tests
+
+To run the test suite:
+
+```bash
+npm test
+```
+
+### Building the Project
+
+To compile the TypeScript code into JavaScript in the `dist` folder:
+
+```bash
+npm run build
+```

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Options for configuring the AgentiumClient.
+ */
+export interface AgentiumClientOptions {
+    /**
+     * The base URL of the Agentium API.
+     * @default https://api.agentium.network
+     */
+    baseURL?: string;
+}
+/**
+ * Represents the status of a user's badge.
+ */
+export interface Badge {
+    status: string;
+}
+/**
+ * The response payload from a successful connect identity call.
+ */
+export interface ConnectIdentityResponse {
+    /**
+     * The user's Privy ID.
+     */
+    privy_user_id: string;
+    /**
+     * The user's Decentralized Identifier (DID).
+     */
+    did: string;
+    /**
+     * Information about the user's badge status.
+     */
+    badge: Badge;
+}
+/**
+ * Custom error class for API-related errors from the AgentiumClient.
+ */
+export declare class AgentiumApiError extends Error {
+    readonly statusCode: number | undefined;
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * A client for interacting with the Agentium API.
+ */
+export declare class AgentiumClient {
+    private readonly axiosInstance;
+    private readonly DEFAULT_BASE_URL;
+    private readonly CONNECT_PATH;
+    /**
+     * Creates an instance of the AgentiumClient.
+     * @param options - Configuration options for the client.
+     */
+    constructor(options?: AgentiumClientOptions);
+    /**
+     * Connects a Google identity to an Agentium identity.
+     * @param googleToken - The JWT token obtained from Google Sign-In.
+     * @returns A promise that resolves with the connection response, containing the user's DID and Privy ID.
+     * @throws {AgentiumApiError} Will throw a custom API error if the call fails.
+     *  - **400 (Bad Request):** The request was malformed (e.g., missing `id_token`).
+     *  - **401 (Unauthorized):** The provided JWT token is invalid or expired.
+     *  - **500 (Internal Server Error):** An unexpected error occurred on the server.
+     */
+    connectGoogleIdentity(googleToken: string): Promise<ConnectIdentityResponse>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,KAAK,EAAE,KAAK,CAAC;CACd;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAgB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEnC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAKjD;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkC;IACnE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;IAEvD;;;OAGG;gBACS,OAAO,GAAE,qBAA0B;IAO/C;;;;;;;;OAQG;IACG,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;CAcnF"}

package/dist/index.js

@@ -0,0 +1,58 @@
+// SPDX-FileCopyrightText: 2025 Semiotic AI, Inc.
+//
+// SPDX-License-Identifier: MIT
+import axios, { isAxiosError } from 'axios';
+/**
+ * Custom error class for API-related errors from the AgentiumClient.
+ */
+export class AgentiumApiError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.name = 'AgentiumApiError';
+        this.statusCode = statusCode;
+    }
+}
+/**
+ * A client for interacting with the Agentium API.
+ */
+export class AgentiumClient {
+    axiosInstance;
+    DEFAULT_BASE_URL = 'https://api.agentium.network';
+    CONNECT_PATH = '/v1/identity/connect';
+    /**
+     * Creates an instance of the AgentiumClient.
+     * @param options - Configuration options for the client.
+     */
+    constructor(options = {}) {
+        const baseURL = options.baseURL || this.DEFAULT_BASE_URL;
+        this.axiosInstance = axios.create({
+            baseURL: baseURL,
+        });
+    }
+    /**
+     * Connects a Google identity to an Agentium identity.
+     * @param googleToken - The JWT token obtained from Google Sign-In.
+     * @returns A promise that resolves with the connection response, containing the user's DID and Privy ID.
+     * @throws {AgentiumApiError} Will throw a custom API error if the call fails.
+     *  - **400 (Bad Request):** The request was malformed (e.g., missing `id_token`).
+     *  - **401 (Unauthorized):** The provided JWT token is invalid or expired.
+     *  - **500 (Internal Server Error):** An unexpected error occurred on the server.
+     */
+    async connectGoogleIdentity(googleToken) {
+        try {
+            const response = await this.axiosInstance.post(this.CONNECT_PATH, {
+                id_token: googleToken,
+            });
+            return response.data;
+        }
+        catch (error) {
+            if (isAxiosError(error)) {
+                throw new AgentiumApiError(error.message, error.response?.status);
+            }
+            // Re-throw other unexpected errors
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,EAAE;AACF,+BAA+B;AAE/B,OAAO,KAAK,EAAE,EAAE,YAAY,EAAsB,MAAM,OAAO,CAAC;AAsChE;;GAEG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzB,UAAU,CAAqB;IAE/C,YAAY,OAAe,EAAE,UAAmB;QAC9C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,cAAc;IACR,aAAa,CAAgB;IAC7B,gBAAgB,GAAG,8BAA8B,CAAC;IAClD,YAAY,GAAG,sBAAsB,CAAC;IAEvD;;;OAGG;IACH,YAAY,UAAiC,EAAE;QAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,gBAAgB,CAAC;QACzD,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC;YAChC,OAAO,EAAE,OAAO;SACjB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,qBAAqB,CAAC,WAAmB;QAC7C,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAA0B,IAAI,CAAC,YAAY,EAAE;gBACzF,QAAQ,EAAE,WAAW;aACtB,CAAC,CAAC;YACH,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;gBACxB,MAAM,IAAI,gBAAgB,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YACpE,CAAC;YACD,mCAAmC;YACnC,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/package.json

@@ -1,10 +1,23 @@
 {
   "name": "@semiotic-labs/agentium-sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
+  "type": "module",
   "description": "",
-  "main": "index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "vitest",
+    "build": "tsc",
+    "docs": "typedoc",
+    "lint": "eslint src/**/*.ts",
+    "format:check": "prettier --check .",
+    "format:write": "prettier --write .",
+    "check": "npm run lint && npm run format:check",
+    "reuse:check": "reuse lint",
+    "reuse:write": "reuse annotate --license MIT --copyright \"Semiotic AI, Inc.\" --year 2025 -r . --fallback-dot-license --skip-existing"
   },
   "repository": {
     "type": "git",
@@ -12,9 +25,34 @@
   },
   "keywords": [],
   "author": "",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/semiotic-agentium/agentium-sdk/issues"
   },
-  "homepage": "https://github.com/semiotic-agentium/agentium-sdk#readme"
+  "homepage": "https://github.com/semiotic-agentium/agentium-sdk#readme",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "axios-mock-adapter": "^2.1.0",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "prettier": "^3.7.4",
+    "ts-node": "^10.9.2",
+    "typedoc": "^0.28.15",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.48.1",
+    "vitest": "^4.0.15"
+  },
+  "dependencies": {
+    "axios": "^1.13.2"
+  }
 }