@heysummon/consumer-sdk 0.1.1 → 0.2.7

package/LICENSE.md

@@ -0,0 +1,87 @@
+# License
+
+Portions of this software are licensed as follows:
+
+- Source code files that contain ".cloud." in their filename or ".cloud" in their dirname are NOT licensed under
+  the Sustainable Use License.
+  To use source code files that contain ".cloud." in their filename or ".cloud" in their dirname you must hold a
+  valid HeySummon Cloud License specifically allowing you access to such source code files and as defined
+  in "LICENSE_CLOUD.md".
+- All third party components incorporated into the HeySummon Software are licensed under the original license
+  provided by the owner of the applicable component.
+- Content outside of the above mentioned files or restrictions is available under the "Sustainable Use
+  License" as defined below.
+
+## Sustainable Use License
+
+Version 1.0
+
+### Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+### Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license
+to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+### Limitations
+
+You may use or modify the software only for your own internal business purposes or for non-commercial or
+personal use. You may distribute the software or provide it to others only if you do so free of charge for
+non-commercial purposes. You may not alter, remove, or obscure any licensing, copyright, or other notices of
+the licensor in the software. Any use of the licensor's trademarks is subject to applicable law.
+
+### Patents
+
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to
+license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case
+subject to the limitations and conditions in this license. This license does not cover any patent claims that
+you cause to be infringed by modifications or additions to the software. If you or your company make any
+written claim that the software infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company makes such a claim, your patent
+license ends immediately for work on behalf of your company.
+
+### Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these
+terms. If you modify the software, you must include in any modified copies of the software a prominent notice
+stating that you have modified the software.
+
+### No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+### Termination
+
+If you use the software in violation of these terms, such use is not licensed, and your license will
+automatically terminate. If the licensor provides you with a notice of your violation, and you cease all
+violation of this license no later than 30 days after you receive that notice, your license will be reinstated
+retroactively. However, if you violate these terms after such reinstatement, any additional violation of these
+terms will cause your license to terminate automatically and permanently.
+
+### No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will
+not be liable to you for any damages arising out of these terms or the use or nature of the software, under
+any kind of legal claim.
+
+### Definitions
+
+The "licensor" is Thomas Ansems and HeySummon.
+
+The "software" is the software the licensor makes available under these terms, including any portion of it.
+
+"You" refers to the individual or entity agreeing to these terms.
+
+"Your company" is any legal entity, sole proprietorship, or other kind of organization that you work for, plus
+all organizations that have control over, are under the control of, or are under common control with that
+organization. Control means ownership of substantially all the assets of an entity, or the power to direct its
+management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+"Your license" is the license granted to you for the software under these terms.
+
+"Use" means anything you do with the software requiring your license.
+
+"Trademark" means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,225 @@
+# @heysummon/consumer-sdk
+
+TypeScript SDK for [HeySummon](https://heysummon.ai) consumers (AI agents). Submit help requests to human experts, poll for responses, and optionally encrypt messages end-to-end.
+
+## Install
+
+```bash
+pnpm install @heysummon/consumer-sdk
+```
+
+## Quick Start
+
+```typescript
+import { HeySummonClient } from "@heysummon/consumer-sdk";
+
+const client = new HeySummonClient({
+  baseUrl: "https://cloud.heysummon.ai",
+  apiKey: process.env.HEYSUMMON_API_KEY!,
+});
+
+// Submit a help request
+const result = await client.submitRequest({
+  question: "Should I proceed with the database migration?",
+});
+
+// Poll for the response
+const status = await client.getRequestStatus(result.requestId!);
+console.log(status.response);
+```
+
+## Client API
+
+### `HeySummonClient`
+
+All methods authenticate via the `x-api-key` header using the API key provided at construction.
+
+```typescript
+const client = new HeySummonClient({ baseUrl, apiKey });
+```
+
+| Method | Description |
+|--------|-------------|
+| `whoami()` | Identify which expert this API key is linked to |
+| `submitRequest(opts)` | Submit a help request to a human expert |
+| `getRequestStatus(requestId)` | Get the current status of a request |
+| `getRequestByRef(refCode)` | Look up a request by its `HS-XXXX` reference code |
+| `getPendingEvents()` | Poll for pending events (new messages, responses, etc.) |
+| `ackEvent(requestId)` | Acknowledge a specific event |
+| `getMessages(requestId)` | Fetch the full message history for a request |
+| `reportTimeout(requestId)` | Report that the client's poll timed out |
+
+### Submit Request Options
+
+```typescript
+interface SubmitRequestOptions {
+  question: string;
+  messages?: Array<{ role: string; content: string }>;
+  signPublicKey?: string;
+  encryptPublicKey?: string;
+  expertName?: string;
+  requiresApproval?: boolean;
+}
+```
+
+### Approval Requests
+
+Set `requiresApproval: true` to show Approve/Deny buttons to the expert instead of a free-text reply prompt. The decision is delivered as a message event:
+
+```typescript
+const result = await client.submitRequest({
+  question: "Should I proceed with the $5,000 purchase?",
+  requiresApproval: true,
+});
+
+// Poll until the expert decides
+const status = await client.getRequestStatus(result.requestId!);
+if (status.status === "responded") {
+  const messages = await client.getMessages(result.requestId!);
+  // Expert message contains "approved" or "denied"
+}
+```
+
+### Error Handling
+
+The client throws `HeySummonHttpError` for non-2xx responses:
+
+```typescript
+import { HeySummonHttpError } from "@heysummon/consumer-sdk";
+
+try {
+  await client.submitRequest({ question: "..." });
+} catch (err) {
+  if (err instanceof HeySummonHttpError) {
+    console.error(err.status, err.body);
+    if (err.isAuthError) {
+      // 401, 403, or 404
+    }
+  }
+}
+```
+
+## End-to-End Encryption
+
+The SDK includes X25519 + AES-256-GCM encryption with Ed25519 signatures.
+
+### Ephemeral Keys (in-memory)
+
+```typescript
+import { generateEphemeralKeys } from "@heysummon/consumer-sdk";
+
+const keys = generateEphemeralKeys();
+// { signPublicKey: "hex...", encryptPublicKey: "hex..." }
+
+await client.submitRequest({
+  question: "Sensitive question",
+  signPublicKey: keys.signPublicKey,
+  encryptPublicKey: keys.encryptPublicKey,
+});
+```
+
+### Persistent Keys (file-based)
+
+```typescript
+import { generatePersistentKeys, loadPublicKeys } from "@heysummon/consumer-sdk";
+
+// Generate and save to disk
+const keys = generatePersistentKeys("/path/to/keys");
+
+// Load existing keys without regenerating
+const existing = loadPublicKeys("/path/to/keys");
+```
+
+### Encrypt / Decrypt
+
+```typescript
+import { encrypt, decrypt } from "@heysummon/consumer-sdk";
+
+const encrypted = encrypt(
+  "Hello, human!",
+  "/path/to/recipient_encrypt_public.pem",
+  "/path/to/own_sign_private.pem",
+  "/path/to/own_encrypt_private.pem"
+);
+
+const plaintext = decrypt(
+  encrypted,
+  "/path/to/sender_encrypt_public.pem",
+  "/path/to/sender_sign_public.pem",
+  "/path/to/own_encrypt_private.pem"
+);
+```
+
+## Expert Store
+
+Manage multiple expert registrations in a local JSON file:
+
+```typescript
+import { ExpertStore } from "@heysummon/consumer-sdk";
+
+const store = new ExpertStore("/path/to/experts.json");
+
+store.add({
+  name: "My Expert",
+  apiKey: "hs_cli_...",
+  expertId: "...",
+  expertName: "Expert Name",
+});
+
+const expert = store.findByName("My Expert");
+const defaultExpert = store.getDefault();
+```
+
+## CLI
+
+The package includes a CLI for use in shell scripts and automation:
+
+```bash
+pnpm dlx @heysummon/consumer-sdk <command> [options]
+```
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `submit-and-poll` | Submit a request and wait for a response |
+| `add-expert` | Register an expert by API key |
+| `list-experts` | List registered experts |
+| `check-status` | Check the status of an existing request |
+| `keygen` | Generate persistent encryption key pairs |
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `HEYSUMMON_BASE_URL` | Yes | Platform URL (e.g. `https://cloud.heysummon.ai`) |
+| `HEYSUMMON_API_KEY` | Varies | Consumer API key (not needed if using expert store) |
+| `HEYSUMMON_EXPERTS_FILE` | No | Path to experts.json for multi-expert setups |
+| `HEYSUMMON_TIMEOUT` | No | Poll timeout in seconds (default: 900) |
+| `HEYSUMMON_POLL_INTERVAL` | No | Poll interval in seconds (default: 3) |
+
+### Examples
+
+```bash
+# Submit and wait for a response
+HEYSUMMON_BASE_URL=https://cloud.heysummon.ai \
+HEYSUMMON_API_KEY=hs_cli_... \
+pnpm dlx @heysummon/consumer-sdk submit-and-poll --question "Should I deploy?"
+
+# Register an expert
+HEYSUMMON_BASE_URL=https://cloud.heysummon.ai \
+HEYSUMMON_EXPERTS_FILE=./experts.json \
+pnpm dlx @heysummon/consumer-sdk add-expert --key hs_cli_... --alias "DevOps Lead"
+
+# Check request status
+HEYSUMMON_BASE_URL=https://cloud.heysummon.ai \
+HEYSUMMON_API_KEY=hs_cli_... \
+pnpm dlx @heysummon/consumer-sdk check-status --ref HS-1234
+
+# Generate encryption keys
+pnpm dlx @heysummon/consumer-sdk keygen --dir ./keys
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -3,12 +3,12 @@
  * HeySummon Consumer SDK CLI
  *
  * Shared CLI entry point used by both Claude Code and OpenClaw skill scripts.
- * Subcommands: submit, submit-and-poll, add-provider, list-providers,
- *              check-status, watch, keygen
+ * Subcommands: submit-and-poll, add-expert, list-experts,
+ *              check-status, keygen
  *
  * All config comes from environment variables (set by the calling bash wrapper):
- *   HEYSUMMON_BASE_URL, HEYSUMMON_API_KEY, HEYSUMMON_PROVIDERS_FILE,
- *   HEYSUMMON_KEY_DIR, HEYSUMMON_REQUESTS_DIR, HEYSUMMON_TIMEOUT,
+ *   HEYSUMMON_BASE_URL, HEYSUMMON_API_KEY, HEYSUMMON_EXPERTS_FILE,
+ *   HEYSUMMON_TIMEOUT,
  *   HEYSUMMON_POLL_INTERVAL
  */
 export {};