Skip to content

Rewrite SDK around current receipt contract #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
GsCommand merged 2 commits into from
Mar 22, 2026
Merged

Rewrite SDK around current receipt contract #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6989a8e
Rewrite SDK around current receipt contract
GsCommand Mar 22, 2026
b90a99a
Merge branch 'main' into codex/rewrite-sdk-for-commandlayer-receipt-c…
GsCommand Mar 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
169 changes: 36 additions & 133 deletions EXAMPLES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ All examples in this file target:
"alg": "ed25519-sha256",
"canonical": "cl-stable-json-v1",
"signer_id": "runtime.commandlayer.eth",
"hash_sha256": "...",
"hash_sha256": "same-value-as-receipt_id",
"signature_b64": "..."
}
}
Expand All @@ -34,48 +34,19 @@ All examples in this file target:
}
```

## 2. TypeScript examples

### Create client
## TypeScript

```ts
import { createClient } from "@commandlayer/sdk";

const client = createClient({
actor: "examples-ts",
runtime: "https://runtime.commandlayer.org"
});
```
import { createClient, extractReceiptVerb, verifyReceipt } from "@commandlayer/sdk";

### Summarize

```ts
const client = createClient({ actor: "examples-ts" });
const response = await client.summarize({
content: "CommandLayer defines semantic agent verbs.",
content: "CommandLayer defines verifiable agent verbs.",
style: "bullet_points"
});

console.log(response.receipt.result?.summary);
```

### Analyze

```ts
const response = await client.analyze({
content: "Invoice total: $1200",
goal: "detect finance intent"
});
```

### Classify

```ts
const response = await client.classify({
content: "Contact support@example.com"
});
```

### Clean
console.log(extractReceiptVerb(response));
console.log(response.receipt.metadata.receipt_id);

```ts
const response = await client.clean({
Expand Down Expand Up @@ -172,120 +143,52 @@ import { verifyReceipt } from "@commandlayer/sdk";
const result = await verifyReceipt(response.receipt, {
publicKey: "ed25519:BASE64_PUBLIC_KEY"
});
console.log(verified.ok);
```

### Python, explicit key
## Python

```python
from commandlayer import verify_receipt

result = verify_receipt(response["receipt"], public_key="ed25519:BASE64_PUBLIC_KEY")
```
from commandlayer import create_client, verify_receipt
from commandlayer.verify import extract_receipt_verb

### ENS-backed verification

```ts
const result = await verifyReceipt(response.receipt, {
ens: {
name: "summarizeagent.eth",
rpcUrl: process.env.MAINNET_RPC_URL!
}
});
```

```python
result = verify_receipt(
response["receipt"],
ens={"name": "summarizeagent.eth", "rpcUrl": "https://mainnet.infura.io/v3/YOUR_KEY"},
client = create_client(actor="examples-py")
response = client.summarize(
content="CommandLayer defines verifiable agent verbs.",
style="bullet_points",
)
```

## 5. CLI examples

### Summarize

```bash
commandlayer summarize \
--content "CommandLayer defines semantic verbs." \
--style bullet_points \
--json
```

### Analyze

```bash
commandlayer analyze \
--content "Invoice total: $500" \
--goal "detect finance intent" \
--json
print(extract_receipt_verb(response))
print(response["receipt"]["metadata"]["receipt_id"])
print(verify_receipt(response["receipt"], public_key="ed25519:BASE64_PUBLIC_KEY")["ok"])
```

### Verify a saved receipt

```bash
commandlayer verify \
--file receipt.json \
--public-key "ed25519:BASE64_PUBLIC_KEY"
```

## 6. Runtime override

### TypeScript

```ts
const client = createClient({
actor: "override-example",
runtime: "https://staging-runtime.commandlayer.org"
});
```

### Python

```python
client = create_client(
actor="override-example",
runtime="https://staging-runtime.commandlayer.org",
)
```
## Explicit request building

## 7. Persist the canonical receipt
### Commons

```ts
import { writeFile } from "node:fs/promises";
import { buildCommonsRequest } from "@commandlayer/sdk";

await writeFile("receipt.json", JSON.stringify(response.receipt, null, 2));
const payload = buildCommonsRequest("parse", {
input: { content: '{"a":1}', content_type: "json", mode: "strict" },
limits: { max_output_tokens: 300 }
}, { actor: "examples-ts" });
```

```python
import json
from pathlib import Path

Path("receipt.json").write_text(json.dumps(response["receipt"], indent=2), encoding="utf-8")
```

## 8. Error handling

### TypeScript

```ts
import { CommandLayerError } from "@commandlayer/sdk";
from commandlayer import build_commons_request

try {
await client.summarize({ content: "" });
} catch (error) {
if (error instanceof CommandLayerError) {
console.error(error.statusCode, error.message, error.details);
}
}
payload = build_commons_request(
"parse",
{
"input": {"content": '{"a":1}', "content_type": "json", "mode": "strict"},
"limits": {"max_output_tokens": 300},
},
actor="examples-py",
)
```

### Python
### Commercial request shaping

```python
from commandlayer import CommandLayerError

try:
client.summarize(content="")
except CommandLayerError as error:
print(error.status_code, error, error.details)
```
Commercial request shaping is intentionally separate from Commons examples. Use the dedicated `buildCommercialRequest` / `build_commercial_request` helper only if you are integrating a payment-aware flow outside this repo's first-class runtime client surface.
86 changes: 10 additions & 76 deletions QUICKSTART.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,44 +1,27 @@
# CommandLayer SDK Quickstart

Goal: install the SDK, run one verb, inspect the receipt, verify it, and reproduce the call in under three minutes.

## 1. Install

### TypeScript / JavaScript

```bash
npm install @commandlayer/sdk
```

### Python

```bash
pip install commandlayer
```

### CLI

The CLI ships with the npm package:

```bash
npm install -g @commandlayer/sdk
```

## 2. Make your first call
## 2. Make one call

### TypeScript

```ts
import { createClient } from "@commandlayer/sdk";

const client = createClient({ actor: "quickstart-ts" });

const response = await client.summarize({
content: "CommandLayer makes agent execution verifiable.",
style: "bullet_points"
});

console.log(response.receipt.result?.summary);
console.log(response.receipt.metadata.receipt_id);
```

### Python
Expand All @@ -53,6 +36,7 @@ response = client.summarize(
)

print(response["receipt"]["result"]["summary"])
print(response["receipt"]["metadata"]["receipt_id"])
```

## 3. Inspect the response
Expand Down Expand Up @@ -89,67 +73,17 @@ Use `response.receipt` as the durable protocol artifact. `runtime_metadata` is o

```ts
import { verifyReceipt } from "@commandlayer/sdk";

const result = await verifyReceipt(response.receipt, {
publicKey: "ed25519:BASE64_PUBLIC_KEY"
});

console.log(result.ok);
await verifyReceipt(response.receipt, { publicKey: "ed25519:BASE64_PUBLIC_KEY" });
```

### Python

```python
from commandlayer import verify_receipt

result = verify_receipt(
response["receipt"],
public_key="ed25519:BASE64_PUBLIC_KEY",
)
print(result["ok"])
```

### ENS-backed verification

Use the same signer-discovery model in both SDKs:
- agent ENS TXT: `cl.receipt.signer`
- signer ENS TXT: `cl.sig.pub`
- signer ENS TXT: `cl.sig.kid`

## 5. Try the CLI

```bash
commandlayer summarize \
--content "CommandLayer makes agent execution verifiable." \
--style bullet_points \
--json
```

Save the returned JSON and verify it:

```bash
commandlayer verify \
--file receipt.json \
--public-key "ed25519:BASE64_PUBLIC_KEY"
verify_receipt(response["receipt"], public_key="ed25519:BASE64_PUBLIC_KEY")
```

## 6. What is stable today?

Stable in this repo:
- Protocol-Commons v1.1.0 verb surface,
- canonical signed receipt verification,
- ENS signer discovery helpers,
- TypeScript SDK `@commandlayer/sdk` v1.1.0,
- Python SDK `commandlayer` v1.1.0.

Not claimed as first-class SDK support here:
- Protocol-Commercial payment flows,
- runtime-specific orchestration metadata beyond the generic `runtime_metadata` envelope.

## Next steps
## 4. Remember the contract

- More recipes: `EXAMPLES.md`
- Package docs: `typescript-sdk/README.md`, `python-sdk/README.md`
- Maintainer notes: `DEVELOPER_EXPERIENCE.md`
- Release guide: `RELEASE_GUIDE.md`
- Deployment checklist: `DEPLOYMENT_GUIDE.md`
- Persist `response.receipt`.
- Treat `response.runtime_metadata` as optional unsigned context.
- Treat `receipt.metadata.receipt_id` as the receipt hash identifier.
- Read the verb from `receipt.x402.verb`.
Loading
Loading