Skip to content

Commit 9c878a6

Browse files
agentstacktechagentstacktech
committed
initial sdk
0 parents  commit 9c878a6

586 files changed

Lines changed: 95385 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main, develop]
6+
pull_request:
7+
branches: [main, develop]
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
15+
- name: Setup Node.js
16+
uses: actions/setup-node@v4
17+
with:
18+
node-version: '22'
19+
cache: 'npm'
20+
21+
- name: Install dependencies
22+
run: npm install
23+
24+
- name: Build
25+
run: npm run build
26+
27+
- name: Docs and export guards
28+
run: |
29+
npm run check:docs-urls
30+
npm run check:package-exports
31+
npm run check:docs-api-symbols
32+
33+
- name: Economy + finance SDK parity
34+
run: npm run check:economy-parity && npm run check:finance-parity
35+
36+
test:
37+
runs-on: ubuntu-latest
38+
needs: build
39+
steps:
40+
- uses: actions/checkout@v4
41+
42+
- name: Setup Node.js
43+
uses: actions/setup-node@v4
44+
with:
45+
node-version: '22'
46+
cache: 'npm'
47+
48+
- name: Install dependencies
49+
run: npm install
50+
51+
- name: Run tests (publish gate subset)
52+
run: npm run test -w @agentstack/sdk -- --testPathPattern="(agentstackEndpoints|validateAppManifest)"
53+
54+
lint:
55+
runs-on: ubuntu-latest
56+
needs: build
57+
steps:
58+
- uses: actions/checkout@v4
59+
60+
- name: Setup Node.js
61+
uses: actions/setup-node@v4
62+
with:
63+
node-version: '22'
64+
cache: 'npm'
65+
66+
- name: Install dependencies
67+
run: npm install
68+
69+
- name: Lint
70+
run: npm run lint

‎.github/workflows/publish.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Publish to npm
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
jobs:
8+
publish-sdk:
9+
runs-on: ubuntu-latest
10+
permissions:
11+
contents: read
12+
id-token: write
13+
steps:
14+
- uses: actions/checkout@v4
15+
16+
- name: Setup Node.js
17+
uses: actions/setup-node@v4
18+
with:
19+
node-version: '22'
20+
cache: 'npm'
21+
registry-url: 'https://registry.npmjs.org'
22+
23+
- name: Install dependencies
24+
run: npm install
25+
26+
- name: Build
27+
run: npm run build
28+
29+
- name: Publish @agentstack/sdk
30+
run: npm publish -w @agentstack/sdk --provenance --access public
31+
env:
32+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
33+
34+
publish-react:
35+
runs-on: ubuntu-latest
36+
needs: publish-sdk
37+
permissions:
38+
contents: read
39+
id-token: write
40+
steps:
41+
- uses: actions/checkout@v4
42+
43+
- name: Setup Node.js
44+
uses: actions/setup-node@v4
45+
with:
46+
node-version: '22'
47+
cache: 'npm'
48+
registry-url: 'https://registry.npmjs.org'
49+
50+
- name: Install dependencies
51+
run: npm install
52+
53+
- name: Build
54+
run: npm run build
55+
56+
- name: Publish @agentstack/react
57+
run: npm publish -w @agentstack/react --provenance --access public
58+
env:
59+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎.gitignore‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# Build output
5+
dist/
6+
*.tsbuildinfo
7+
8+
# Environment
9+
.env
10+
.env.local
11+
.env.*.local
12+
13+
# Logs
14+
*.log
15+
npm-debug.log*
16+
yarn-debug.log*
17+
yarn-error.log*
18+
19+
# IDE
20+
.idea/
21+
.vscode/
22+
*.swp
23+
*.swo
24+
25+
# OS
26+
.DS_Store
27+
Thumbs.db
28+
29+
# Test coverage
30+
coverage/
31+
.nyc_output/
32+
33+
# Temporary files
34+
*.tmp
35+
*.temp
36+
.cache/

‎.npmrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
legacy-peer-deps=true

‎AGENTS.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# AgentStack SDK — guide for AI agents
2+
3+
**Genetic tag:** `repo.platform.sdk.ai_surface.gen1`
4+
**North star:** fast, low-error construction of apps and sites on AgentStack via typed SDK + self-description.
5+
6+
---
7+
8+
## 60-second bootstrap
9+
10+
```typescript
11+
import { AgentStackSDK, resolveAgentStackApiBase } from '@agentstack/sdk';
12+
13+
const sdk = new AgentStackSDK({ apiBase: resolveAgentStackApiBase() });
14+
15+
// 1) Discover surfaces (read before calling APIs)
16+
const catalog = sdk.getModuleCatalog();
17+
const matrix = sdk.getCapabilityMatrix();
18+
19+
// 2) Auth
20+
await sdk.platform.auth.login({
21+
email: process.env.AGENTSTACK_EMAIL!,
22+
password: process.env.AGENTSTACK_PASSWORD!,
23+
});
24+
25+
// 3) First REST call
26+
const projects = await sdk.platform.api.getProjects();
27+
```
28+
29+
**Production API:** `https://agentstack.tech` (default via `resolveAgentStackApiBase()`).
30+
**Local Core:** `AGENTSTACK_API_BASE=http://localhost:8000/api`
31+
32+
---
33+
34+
## Discover → validate → execute
35+
36+
| Step | API | When |
37+
|------|-----|------|
38+
| Discover | `sdk.getModuleCatalog()` | Pick module id, `accessPaths`, `aiHints`, `examples` |
39+
| Gate | `sdk.getCapabilityMatrix()` | Skip disabled `domain` modules |
40+
| Validate | `validateAppManifest()`, `parseTaskManifest()` | Before writes |
41+
| Execute | `sdk.platform.*`, `sdk.protocol.*` | REST + commands + snapshots |
42+
| Deploy site | `sdk.hosting.quickStart()` | Static HTML hosting |
43+
44+
Full recipes: [docs/AI_APPLICATION_FACTORY.md](docs/AI_APPLICATION_FACTORY.md)
45+
46+
---
47+
48+
## Decision tree
49+
50+
- **CRUD / projects / users** → `sdk.platform.api` or `sdk.platform.dna`
51+
- **DNA command bus** → `sdk.platform.protocol.executeCommand` (not raw `/commands` fetch)
52+
- **Rules engine** → `sdk.platform.command` or `protocol.executeRulesCommand`
53+
- **Cached read model** → `sdk.platform.protocol.readThroughSnapshot`
54+
- **MCP automation** → `https://agentstack.tech/mcp` (`agentstack.execute`) — mirror of platform actions
55+
- **Tenant apps** → never `sdk.admin` (platform operator only)
56+
57+
---
58+
59+
## Genetic routing (hot paths)
60+
61+
| Tag | Doc / code |
62+
|-----|------------|
63+
| `repo.platform.sdk.gen1` | [AI_INDEX.md](AI_INDEX.md) |
64+
| `repo.platform.sdk.agent_protocol.gen1` | [../docs/AGENT_PROTOCOL_QUICKSTART.md](../docs/AGENT_PROTOCOL_QUICKSTART.md) |
65+
| `repo.platform.sdk.ai_surface.gen1` | [../docs/SDK_AI_SURFACE.md](../docs/SDK_AI_SURFACE.md) |
66+
| `repo.platform.app_manifest.gen1` | `@agentstack/sdk/manifest` · `appManifestSchema` |
67+
| `sdk.capability_tasks.gen1` | `@agentstack/sdk/capability-tasks` |
68+
| `sdk.hosting.gen2` | `sdk.hosting.quickStart` |
69+
| `sdk.commerce.facade.gen1` | `sdk.commerce` · `@agentstack/sdk/commerce/*` |
70+
71+
---
72+
73+
## Anti-patterns
74+
75+
- Do not use `fetch('/api/...')` when `sdk.platform` or `sdk.protocol` exists.
76+
- Do not treat `sdk.protocol.searchSnapshots` as server full-text search (cache scan only).
77+
- Do not call `sdk.projects.get(uuid)` — `projects` is **8DNA** `DNATableWrapper`; use `sdk.platform.api.getProject(id)`.
78+
- Do not use `sdk.admin` in tenant integrations.
79+
- Check `getCapabilityMatrix()` before calling optional domains (`payments`, `gameData`, …).
80+
81+
---
82+
83+
## Links
84+
85+
- Swagger: https://agentstack.tech/swagger
86+
- MCP: https://agentstack.tech/mcp
87+
- Module catalog: [docs/SDK_MODULE_CATALOG.md](docs/SDK_MODULE_CATALOG.md)
88+
- Integrator guide: [docs/AI_INTEGRATOR_GUIDE.md](docs/AI_INTEGRATOR_GUIDE.md)
89+
- Errors: [docs/AI_ERROR_ACTION_MATRIX.md](docs/AI_ERROR_ACTION_MATRIX.md)

0 commit comments

Comments
 (0)