Skip to content
This repository was archived by the owner on May 24, 2026. It is now read-only.

Align TypeScript SDK Commons requests with Protocol‑Commons v1.1.0 #24

Closed
GsCommand wants to merge 1 commit into from
Closed

Align TypeScript SDK Commons requests with Protocol‑Commons v1.1.0 #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
209 changes: 35 additions & 174 deletions EXAMPLES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,33 @@
# CommandLayer SDK Examples

Canonical examples for the CommandLayer SDK repo. These examples keep the Commons v1.1.0 story receipt-first: `receipt` is signed, `runtime_metadata` is optional and unsigned, and the `x402` object is protocol metadata rather than a commercial SDK surface.
Canonical examples for the CommandLayer SDK repo. These examples keep the Commons v1.1.0 story aligned with the active request and receipt contracts: requests are flat top-level protocol objects, `receipt` is signed, `runtime_metadata` is optional and unsigned, and the `x402` object only appears inside receipts as protocol metadata.

All examples in this file target:
- Protocol-Commons v1.1.0,
- flat request payloads shaped exactly like `schemas/v1.1.0/commons/<verb>/<verb>.request.schema.json`,
- canonical signed receipts returned as `response.receipt`, and
- optional execution context returned as `response.runtime_metadata`.

## 1. Canonical response envelope
## 1. Canonical summarize request

```json
{
"verb": "summarize",
"version": "1.1.0",
"input": "CommandLayer defines semantic agent verbs.",
"mode": "brief"
}
```

## 2. Canonical response envelope

```json
{
"receipt": {
"status": "success",
"x402": {
"verb": "summarize",
"version": "1.1.0",
"version": "1.1.0"
},
"result": {
"summary": "..."
Expand All @@ -39,15 +51,14 @@ All examples in this file target:
}
```

## 2. TypeScript examples
## 3. TypeScript examples

### Create client

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

const client = createClient({
actor: "examples-ts",
runtime: "https://runtime.commandlayer.org"
});
```
Expand All @@ -56,8 +67,8 @@ const client = createClient({

```ts
const response = await client.summarize({
content: "CommandLayer defines semantic agent verbs.",
style: "bullet_points"
input: "CommandLayer defines semantic agent verbs.",
mode: "brief"
});

console.log(response.receipt.result?.summary);
Expand All @@ -67,73 +78,70 @@ console.log(response.receipt.result?.summary);

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

### Classify

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

### Clean

```ts
const response = await client.clean({
content: " test@example.com ",
operations: ["trim", "redact_emails"]
input: " test@example.com ",
mode: "sanitize"
});
```

### Convert

```ts
const response = await client.convert({
content: '{"a":1}',
from: "json",
to: "csv"
input: '{"a":1}',
mode: "structured"
});
```

### Describe

```ts
const response = await client.describe({
subject: "receipt verification",
audience: "general",
detail: "medium"
input: "receipt verification",
mode: "detailed"
});
```

### Explain

```ts
const response = await client.explain({
subject: "receipt verification",
audience: "novice",
style: "step-by-step"
input: "receipt verification",
mode: "stepwise"
});
```

### Format

```ts
const response = await client.format({
content: "a: 1\nb: 2",
to: "table"
input: "a: 1\nb: 2",
mode: "markdown"
});
```

### Parse

```ts
const response = await client.parse({
content: '{ "a": 1 }',
contentType: "json",
input: '{ "a": 1 }',
mode: "strict"
});
```
Expand All @@ -142,154 +150,7 @@ const response = await client.parse({

```ts
const response = await client.fetch({
source: "https://example.com",
include_metadata: true
});
```

## 3. Python examples

```python
from commandlayer import create_client

client = create_client(actor="examples-py")

summary = client.summarize(content="CommandLayer defines semantic agent verbs.", style="bullet_points")
analysis = client.analyze(content="Invoice total: $1200", goal="detect finance intent")
classification = client.classify(content="Contact support@example.com")
cleaned = client.clean(content=" test@example.com ", operations=["trim", "redact_emails"])
converted = client.convert(content='{"a":1}', from_format="json", to_format="csv")
description = client.describe(subject="receipt verification")
explanation = client.explain(subject="receipt verification", style="step-by-step")
formatted = client.format(content="a: 1\nb: 2", to="table")
parsed = client.parse(content='{ "a": 1 }', content_type="json", mode="strict")
fetched = client.fetch(source="https://example.com", include_metadata=True)
```

## 4. Verification examples

### TypeScript, explicit key

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

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

### Python, explicit key

```python
from commandlayer import verify_receipt

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

### 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"},
)
```

## 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
```

### 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"
input: "https://example.com",
mode: "html"
});
```

### Python

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

## 7. Persist the canonical receipt

```ts
import { writeFile } from "node:fs/promises";

await writeFile("receipt.json", JSON.stringify(response.receipt, null, 2));
```

```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";

try {
await client.summarize({ content: "" });
} catch (error) {
if (error instanceof CommandLayerError) {
console.error(error.statusCode, error.message, error.details);
}
}
```

### Python

```python
from commandlayer import CommandLayerError

try:
client.summarize(content="")
except CommandLayerError as error:
print(error.status_code, error, error.details)
```
35 changes: 25 additions & 10 deletions QUICKSTART.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,11 @@ npm install -g @commandlayer/sdk
```ts
import { createClient } from "@commandlayer/sdk";

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

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

console.log(response.receipt.result?.summary);
Expand All @@ -55,7 +55,22 @@ response = client.summarize(
print(response["receipt"]["result"]["summary"])
```

## 3. Inspect the response
## 3. Inspect the request contract

Protocol-Commons v1.1.0 Commons requests are flat top-level objects:

```json
{
"verb": "summarize",
"version": "1.1.0",
"input": "CommandLayer makes agent execution verifiable.",
"mode": "brief"
}
```

Do not send nested `input` objects, `limits`, actor wrappers, or `x402` request metadata for Commons verbs.

## 4. Inspect the response

Both SDKs return the same shape:

Expand Down Expand Up @@ -83,9 +98,9 @@ Both SDKs return the same shape:
}
```

Use `response.receipt` as the durable protocol artifact. `runtime_metadata` is optional execution context. The retained `x402` object carries Commons verb metadata and is not a commercial feature signal.
Use `response.receipt` as the durable protocol artifact. `runtime_metadata` is optional execution context. The retained `x402` object carries Commons verb metadata in receipts and is not a request wrapper or commercial feature signal.

## 4. Verify the receipt
## 5. Verify the receipt

### TypeScript

Expand Down Expand Up @@ -118,12 +133,12 @@ Use the same signer-discovery model in both SDKs:
- signer ENS TXT: `cl.sig.pub`
- signer ENS TXT: `cl.sig.kid`

## 5. Try the CLI
## 6. Try the CLI

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

Expand All @@ -135,7 +150,7 @@ commandlayer verify \
--public-key "ed25519:BASE64_PUBLIC_KEY"
```

## 6. What is stable today?
## 7. What is stable today?

Stable in this repo:
- Protocol-Commons v1.1.0 verb surface,
Expand Down
Loading
Loading