tally-sdk 0.1.0

package/.opencode/skills/openspec-propose/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.4.1"
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx-apply
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `resolvedOutputPath`: Resolved path or pattern to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure and write it to `resolvedOutputPath`
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx-apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

package/.opencode/skills/openspec-sync-specs/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: openspec-sync-specs
+description: Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.4.1"
+---
+
+Sync delta specs from a change to main specs.
+
+This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have delta specs (under `specs/` directory).
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Resolve change context**
+
+   Run:
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+
+   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace spec sync is not supported in this slice and STOP. Do not fall back to repo-local paths or edit linked repos.
+
+3. **Find delta specs**
+
+   Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the list of delta spec files.
+
+   Each delta spec file contains sections like:
+   - `## ADDED Requirements` - New requirements to add
+   - `## MODIFIED Requirements` - Changes to existing requirements
+   - `## REMOVED Requirements` - Requirements to remove
+   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
+
+   If no delta specs found, inform user and stop.
+
+4. **For each delta spec, apply changes to main specs**
+
+   For each repo-local capability delta spec path returned by the CLI:
+
+   a. **Read the delta spec** to understand the intended changes
+
+   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
+
+   c. **Apply changes intelligently**:
+
+      **ADDED Requirements:**
+      - If requirement doesn't exist in main spec → add it
+      - If requirement already exists → update it to match (treat as implicit MODIFIED)
+
+      **MODIFIED Requirements:**
+      - Find the requirement in main spec
+      - Apply the changes - this can be:
+        - Adding new scenarios (don't need to copy existing ones)
+        - Modifying existing scenarios
+        - Changing the requirement description
+      - Preserve scenarios/content not mentioned in the delta
+
+      **REMOVED Requirements:**
+      - Remove the entire requirement block from main spec
+
+      **RENAMED Requirements:**
+      - Find the FROM requirement, rename to TO
+
+   d. **Create new main spec** if capability doesn't exist yet:
+      - Create `openspec/specs/<capability>/spec.md`
+      - Add Purpose section (can be brief, mark as TBD)
+      - Add Requirements section with the ADDED requirements
+
+5. **Show summary**
+
+   After applying all changes, summarize:
+   - Which capabilities were updated
+   - What changes were made (requirements added/modified/removed/renamed)
+
+**Delta Spec Format Reference**
+
+```markdown
+## ADDED Requirements
+
+### Requirement: New Feature
+The system SHALL do something new.
+
+#### Scenario: Basic case
+- **WHEN** user does X
+- **THEN** system does Y
+
+## MODIFIED Requirements
+
+### Requirement: Existing Feature
+#### Scenario: New scenario to add
+- **WHEN** user does A
+- **THEN** system does B
+
+## REMOVED Requirements
+
+### Requirement: Deprecated Feature
+
+## RENAMED Requirements
+
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+**Key Principle: Intelligent Merging**
+
+Unlike programmatic merging, you can apply **partial updates**:
+- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
+- The delta represents *intent*, not a wholesale replacement
+- Use your judgment to merge changes sensibly
+
+**Output On Success**
+
+```
+## Specs Synced: <change-name>
+
+Updated main specs:
+
+**<capability-1>**:
+- Added requirement: "New Feature"
+- Modified requirement: "Existing Feature" (added 1 scenario)
+
+**<capability-2>**:
+- Created new spec file
+- Added requirement: "Another Feature"
+
+Main specs are now updated. The change remains active - archive when implementation is complete.
+```
+
+**Guardrails**
+- Read both delta and main specs before making changes
+- Preserve existing content not mentioned in delta
+- If something is unclear, ask for clarification
+- Show what you're changing as you go
+- The operation should be idempotent - running twice should give same result

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tally Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# tally-sdk
+
+Accounting, tax, and compliance layer for the agent economy.
+
+Tally is an open-source SDK middleware that captures x402 payment metadata at the HTTP layer, persists it to a local SQLite store, and exports structured records to QuickBooks, Xero, and ERP systems.
+
+## Install
+
+```bash
+npm install tally-sdk
+```
+
+## Quick Start
+
+```typescript
+import { createTally } from "tally-sdk";
+
+const tally = createTally({ facilitator: "dexter" });
+
+// Option 1: Use the wrapped fetch directly
+const response = await tally.fetch("https://api.example.com/paid-endpoint");
+
+// Option 2: Monkey-patch global fetch
+tally.wrap();
+const response = await fetch("https://api.example.com/paid-endpoint");
+
+// Restore original fetch
+tally.unwrap();
+
+// Query stored payments
+const payments = await tally.store.list({ facilitator: "dexter" });
+
+// Clean up
+await tally.close();
+```
+
+## API
+
+### `createTally(config: TallyConfig): TallyClient`
+
+Creates a Tally client that observes x402 payment responses and persists metadata.
+
+```typescript
+interface TallyConfig {
+  facilitator: string;  // e.g., "dexter", "coinbase-cdp"
+  store?: Store;        // defaults to SQLite at ./tally.db
+}
+
+interface TallyClient {
+  fetch(input, init): Promise<Response>;  // wrapped fetch
+  wrap(): void;       // monkey-patches globalThis.fetch
+  unwrap(): void;     // restores original globalThis.fetch
+  store: Store;       // direct access to the store
+  close(): Promise<void>;
+}
+```
+
+### `Store` Interface
+
+```typescript
+interface Store {
+  insert(payload: PaymentPayload): Promise<void>;
+  list(opts?: { facilitator?: string; limit?: number; offset?: number }): Promise<PaymentPayload[]>;
+  get(id: string): Promise<PaymentPayload | null>;
+  close(): Promise<void>;
+}
+```
+
+### `PaymentPayload`
+
+```typescript
+interface PaymentPayload {
+  id: string;
+  facilitator: string;
+  requestId: string;
+  fromAddress: string;
+  toAddress: string;
+  amount: string;       // decimal string
+  asset: string;        // e.g., "USDC"
+  chainId: string;      // CAIP-2 format: "eip155:1", "solana:5eykt..."
+  txHash: string;
+  timestamp: number;    // unix ms
+  memo?: string;
+  metadata?: Record<string, unknown>;
+}
+```
+
+## How It Works
+
+1. Agent makes an HTTP request via the wrapped `fetch()`
+2. If the response contains x402 payment headers (`x-facilitator`, `x-request-id`), Tally extracts the payment metadata
+3. The `PaymentPayload` is persisted to the local SQLite store
+4. Export commands (coming soon) generate CSV/QuickBooks/Xero files
+
+## Architecture
+
+```
+Agent Code → wrapped fetch() → x402 payment → PaymentPayload → SQLite Store
+```
+
+Tally is a transparent observer — it never modifies requests or responses. If extraction fails, the agent request proceeds normally.
+
+## License
+
+MIT

package/docs/design-hook-store.md

@@ -0,0 +1,122 @@
+# Tally: x402 Hook + SQLite Store — Design
+
+## Package Structure
+
+```
+tally/
+├── package.json          # tally-sdk
+├── tsconfig.json         # strict TS, Node 20
+├── src/
+│   ├── index.ts          # createTally(), TallyClient — public API
+│   ├── types.ts          # PaymentPayload, Store, TallyConfig
+│   ├── hook.ts           # x402 V2 fetch wrapper
+│   ├── store.ts          # SQLite store (implements Store)
+│   └── cli.ts            # tally export entry (future)
+└── test/
+    ├── hook.test.ts
+    └── store.test.ts
+```
+
+## Core Data Model
+
+### PaymentPayload
+
+The central type that every subsystem produces, consumes, or persists.
+
+- `id: string` — uuid
+- `facilitator: string` — e.g. "dexter", "coinbase-cdp"
+- `requestId: string` — x402 request identifier
+- `fromAddress: string` — sender wallet
+- `toAddress: string` — receiver wallet
+- `amount: string` — decimal string (avoids float precision issues)
+- `asset: string` — e.g. "USDC"
+- `chainId: string` — CAIP-2 format: "eip155:1", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
+- `txHash: string` — on-chain transaction hash
+- `timestamp: number` — unix ms
+- `memo?: string` — Solana extra.memo for reconciliation
+- `metadata?: Record<string, unknown>` — facilitator-specific extras
+
+### Store Interface
+
+```typescript
+interface Store {
+  insert(payload: PaymentPayload): Promise<void>
+  list(opts?: { facilitator?: string; limit?: number; offset?: number }): Promise<PaymentPayload[]>
+  get(id: string): Promise<PaymentPayload | null>
+  close(): Promise<void>
+}
+```
+
+## Public API
+
+```typescript
+// Entry point — creates a Tally client
+function createTally(config: TallyConfig): TallyClient
+
+interface TallyConfig {
+  facilitator: string
+  store?: Store            // defaults to SQLite store at ./tally.db
+}
+
+interface TallyClient {
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>
+  wrap(): void             // monkey-patches globalThis.fetch
+  store: Store             // exposed for direct queries
+  close(): Promise<void>
+}
+```
+
+## x402 Hook
+
+### Wrapping strategy
+
+Two approaches, both exported:
+
+1. **`wrapFetch()`** — monkey-patches `globalThis.fetch`. Zero agent code changes.
+2. **`createFetch()`** — returns a wrapped fetch function. Explicit, composable.
+
+Lifecycle: agent calls fetch → hook adds x402 headers → response returns → hook extracts PaymentPayload from response body + headers → calls `store.insert()` → returns original response.
+
+## SQLite Store
+
+### Schema
+
+```sql
+CREATE TABLE IF NOT EXISTS payments (
+  id          TEXT PRIMARY KEY,
+  facilitator TEXT NOT NULL,
+  request_id  TEXT NOT NULL,
+  from_addr   TEXT NOT NULL,
+  to_addr     TEXT NOT NULL,
+  amount      TEXT NOT NULL,
+  asset       TEXT NOT NULL DEFAULT 'USDC',
+  chain_id    TEXT NOT NULL,
+  tx_hash     TEXT NOT NULL,
+  memo        TEXT,
+  metadata    TEXT,
+  created_at  INTEGER NOT NULL
+);
+
+CREATE INDEX idx_payments_facilitator ON payments(facilitator);
+CREATE INDEX idx_payments_created_at ON payments(created_at);
+```
+
+`metadata` is JSON-stringified. `better-sqlite3` for synchronous, zero-config operation.
+
+### Methods
+
+- `insert(payload)` — INSERT OR IGNORE on id collision
+- `list({ facilitator, limit, offset })` — filtered, paginated query
+- `get(id)` — single row lookup
+- `close()` — close database connection
+
+## Tests
+
+- `test/hook.test.ts` — mock `globalThis.fetch`, verify payload extraction and store insertion
+- `test/store.test.ts` — `:memory:` SQLite, test insert/list/get
+
+## Package Config
+
+- `package.json`: `name: "tally-sdk"`, `type: "module"`, `exports` map
+- `tsconfig.json`: `strict: true`, `target: "ES2022"`, `module: "NodeNext"`
+- No bundler for V1 — ship TypeScript source