beam-protocol-sdk 0.5.0 → 0.5.2

package/README.md

@@ -0,0 +1,97 @@
+# beam-protocol-sdk
+
+TypeScript SDK for Beam Protocol: identity generation, registration, discovery, DID tooling, and signed agent-to-agent messaging.
+
+## Install
+
+```bash
+npm install beam-protocol-sdk
+```
+
+## Quick Start
+
+```ts
+import { BeamClient, BeamIdentity } from 'beam-protocol-sdk'
+
+const identity = BeamIdentity.generate({ agentName: 'assistant', orgName: 'acme' })
+const client = new BeamClient({ identity: identity.export(), directoryUrl: 'https://api.beam.directory' })
+
+await client.register('Acme Assistant', ['conversation.message'])
+const reply = await client.talk('echo@beam.directory', 'Hello from Beam')
+console.log(reply.message)
+```
+
+## Common Usage
+
+### Handle incoming intents
+
+```ts
+client.on('task.execute', async (frame, respond) => {
+  respond({
+    success: true,
+    payload: {
+      receivedFrom: frame.from,
+      intent: frame.intent,
+    },
+  })
+})
+
+await client.connect()
+```
+
+### Search and lookup
+
+```ts
+const directory = client.directory
+const record = await directory.lookup('echo@beam.directory')
+const matches = await directory.search({ capabilities: ['conversation.message'], limit: 10 })
+```
+
+### Work with DID documents and credentials
+
+```ts
+const didDocument = await client.did.resolve('did:beam:echo')
+const domainCredential = await client.credentials.issueDomainVC(client.beamId, 'acme.com')
+const isValid = client.credentials.verify(domainCredential)
+```
+
+## API Reference
+
+### Core classes
+
+- `BeamIdentity` - generate, import, export, sign, verify, and parse Beam IDs
+- `BeamClient` - register agents, connect over WebSocket, send intents, use talk/thread helpers
+- `BeamDirectory` - lookup, search, browse, stats, profile updates, verification, delegation, reporting
+- `BeamDID` - DID resolution and DID document helpers
+- `BeamCredentialsClient` - issue and verify Beam-issued credentials
+
+### Frame helpers
+
+- `createIntentFrame()`
+- `createResultFrame()`
+- `signFrame()`
+- `validateIntentFrame()`
+- `validateResultFrame()`
+
+### Key management helpers
+
+- `exportIdentity()`
+- `importIdentity()`
+- `generateRecoveryPhrase()`
+- `recoverFromPhrase()`
+- `toQRData()`
+- `fromQRData()`
+
+Full API docs: [docs.beam.directory/api/typescript](https://docs.beam.directory/api/typescript)
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## License
+
+Apache-2.0

package/dist/api-key.d.ts

@@ -0,0 +1,2 @@
+export declare function beamIdFromApiKey(apiKey: string): string | null;
+//# sourceMappingURL=api-key.d.ts.map

package/dist/api-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.d.ts","sourceRoot":"","sources":["../src/api-key.ts"],"names":[],"mappings":"AAqBA,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgB9D"}

package/dist/api-key.js

@@ -0,0 +1,34 @@
+const AGENT_API_KEY_PREFIX = 'bk_';
+function normalizeBase64Url(value) {
+    const normalized = value.replace(/-/g, '+').replace(/_/g, '/');
+    const padding = (4 - (normalized.length % 4)) % 4;
+    return normalized.padEnd(normalized.length + padding, '=');
+}
+function base64ToUtf8(base64) {
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(base64, 'base64').toString('utf8');
+    }
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return new TextDecoder().decode(bytes);
+}
+export function beamIdFromApiKey(apiKey) {
+    if (!apiKey.startsWith(AGENT_API_KEY_PREFIX)) {
+        return null;
+    }
+    const encodedBeamId = apiKey.slice(AGENT_API_KEY_PREFIX.length).split('.', 1)[0] ?? '';
+    if (!encodedBeamId) {
+        return null;
+    }
+    try {
+        const beamId = base64ToUtf8(normalizeBase64Url(encodedBeamId));
+        return beamId || null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=api-key.js.map

package/dist/api-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.js","sourceRoot":"","sources":["../src/api-key.ts"],"names":[],"mappings":"AAAA,MAAM,oBAAoB,GAAG,KAAK,CAAA;AAElC,SAAS,kBAAkB,CAAC,KAAa;IACvC,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;IAC9D,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACjD,OAAO,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,GAAG,OAAO,EAAE,GAAG,CAAC,CAAA;AAC5D,CAAC;AAED,SAAS,YAAY,CAAC,MAAc;IAClC,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IACvD,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAA;IAC3B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC3C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACtD,KAAK,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAA;IACzC,CAAC;IACD,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AACxC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,oBAAoB,CAAC,EAAE,CAAC;QAC7C,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,aAAa,GAAG,MAAM,CAAC,KAAK,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IACtF,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,YAAY,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAC,CAAA;QAC9D,OAAO,MAAM,IAAI,IAAI,CAAA;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC"}

package/dist/bip39-wordlist.d.ts

@@ -0,0 +1,2 @@
+export declare const BIP39_ENGLISH: string[];
+//# sourceMappingURL=bip39-wordlist.d.ts.map

package/dist/bip39-wordlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bip39-wordlist.d.ts","sourceRoot":"","sources":["../src/bip39-wordlist.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,aAAa,EAAE,MAAM,EAigEjC,CAAC"}