Skip to content

Commit 6cfb555

Browse files
rcholicrcholic
authored
Merge pull request #3 from SentienceAPI/week3
add specs
2 parents 79c5937 + 3de62cc commit 6cfb555

File tree

9 files changed

+897
-2
lines changed

9 files changed

+897
-2
lines changed

‎.github/workflows/release.yml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
name: Release to npm
2+
3+
on:
4+
release:
5+
types: [published]
6+
workflow_dispatch:
7+
inputs:
8+
version:
9+
description: 'Version to release (e.g., 0.1.0)'
10+
required: true
11+
type: string
12+
13+
jobs:
14+
build-and-publish:
15+
runs-on: ubuntu-latest
16+
17+
steps:
18+
- name: Checkout code
19+
uses: actions/checkout@v4
20+
21+
- name: Set up Node.js
22+
uses: actions/setup-node@v4
23+
with:
24+
node-version: '20'
25+
registry-url: 'https://registry.npmjs.org'
26+
27+
- name: Extract version from tag or input
28+
id: version
29+
run: |
30+
if [ "${{ github.event_name }}" == "release" ]; then
31+
VERSION=${GITHUB_REF#refs/tags/v}
32+
VERSION=${VERSION#refs/tags/}
33+
else
34+
VERSION="${{ github.event.inputs.version }}"
35+
fi
36+
echo "version=$VERSION" >> $GITHUB_OUTPUT
37+
echo "Version: $VERSION"
38+
39+
- name: Update version in package.json
40+
run: |
41+
VERSION="${{ steps.version.outputs.version }}"
42+
npm version $VERSION --no-git-tag-version
43+
44+
- name: Install dependencies
45+
run: |
46+
npm ci
47+
48+
- name: Install Playwright browsers
49+
run: |
50+
npx playwright install chromium
51+
52+
- name: Run tests
53+
run: |
54+
npm test
55+
env:
56+
CI: true
57+
58+
- name: Build package
59+
run: |
60+
npm run build
61+
62+
- name: Publish to npm
63+
run: |
64+
npm publish --access public
65+
env:
66+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
67+
68+
- name: Create GitHub Release
69+
if: github.event_name == 'workflow_dispatch'
70+
uses: softprops/action-gh-release@v1
71+
with:
72+
tag_name: v${{ steps.version.outputs.version }}
73+
name: Release v${{ steps.version.outputs.version }}
74+
body: |
75+
Release v${{ steps.version.outputs.version }} of sentience-ts
76+
77+
## Installation
78+
```bash
79+
npm install sentience-ts@${{ steps.version.outputs.version }}
80+
```
81+
draft: false
82+
prerelease: false
83+
env:
84+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
85+

‎.github/workflows/test.yml‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
name: Test
2+
3+
on:
4+
push:
5+
branches: [ main, develop ]
6+
pull_request:
7+
branches: [ main, develop ]
8+
9+
jobs:
10+
test:
11+
runs-on: ${{ matrix.os }}
12+
strategy:
13+
matrix:
14+
os: [ubuntu-latest, macos-latest, windows-latest]
15+
node-version: ['20']
16+
17+
steps:
18+
- name: Checkout code
19+
uses: actions/checkout@v4
20+
21+
- name: Set up Node.js ${{ matrix.node-version }}
22+
uses: actions/setup-node@v4
23+
with:
24+
node-version: ${{ matrix.node-version }}
25+
26+
- name: Install dependencies
27+
run: |
28+
npm ci --ignore-scripts
29+
30+
- name: Build package
31+
run: |
32+
npm run build
33+
34+
- name: Install Playwright browsers
35+
run: |
36+
npx playwright install chromium
37+
38+
- name: Build extension (if needed)
39+
run: |
40+
if [ -d "../sentience-chrome" ]; then
41+
cd ../sentience-chrome && ./build.sh || echo "Extension build skipped (may not be available in CI)"
42+
else
43+
echo "Extension directory not found, skipping build"
44+
fi
45+
46+
- name: Run tests
47+
run: |
48+
npm test
49+
env:
50+
CI: true
51+

‎.npmignore‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Source files
2+
src/
3+
examples/
4+
tests/
5+
*.ts
6+
!*.d.ts
7+
8+
# Build artifacts (keep dist/)
9+
*.map
10+
*.js.map
11+
*.d.ts.map
12+
13+
# Development files
14+
.git/
15+
.github/
16+
node_modules/
17+
*.log
18+
.DS_Store
19+
.env
20+
.env.local
21+
22+
# IDE
23+
.vscode/
24+
.idea/
25+
*.swp
26+
*.swo
27+
28+
# Test files
29+
coverage/
30+
.nyc_output/
31+
jest.config.js
32+
tsconfig.json
33+
34+
# Documentation (keep README.md)
35+
docs/
36+
*.md
37+
!README.md
38+
39+
# CI/CD
40+
.github/
41+
42+
# Temporary files
43+
*.tmp
44+
*.temp
45+

‎package.json‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
"scripts": {
88
"build": "tsc",
99
"test": "jest",
10+
"prepare": "npm run build",
11+
"prepublishOnly": "npm test && npm run build",
1012
"example:hello": "ts-node examples/hello.ts",
1113
"example:basic": "ts-node examples/basic-agent.ts",
1214
"cli": "ts-node src/cli.ts"
@@ -25,5 +27,30 @@
2527
"ts-jest": "^29.0.0",
2628
"ts-node": "^10.9.0",
2729
"typescript": "^5.0.0"
30+
},
31+
"files": [
32+
"dist",
33+
"spec",
34+
"README.md",
35+
"LICENSE"
36+
],
37+
"keywords": [
38+
"browser-automation",
39+
"playwright",
40+
"ai-agent",
41+
"web-automation",
42+
"sentience"
43+
],
44+
"repository": {
45+
"type": "git",
46+
"url": "https://github.com/SentienceAPI/sentience-ts.git"
47+
},
48+
"bugs": {
49+
"url": "https://github.com/SentienceAPI/sentience-ts/issues"
50+
},
51+
"homepage": "https://github.com/SentienceAPI/sentience-ts#readme",
52+
"license": "MIT",
53+
"engines": {
54+
"node": ">=20.0.0"
2855
}
2956
}

‎spec/README.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Sentience API Specification
2+
3+
This directory contains the **single source of truth** for the API contract between the Chrome extension and SDKs.
4+
5+
## Files
6+
7+
- **`snapshot.schema.json`** - JSON Schema for snapshot response validation
8+
- **`SNAPSHOT_V1.md`** - Human-readable snapshot API contract
9+
- **`sdk-types.md`** - SDK-level type definitions (ActionResult, WaitResult, TraceStep)
10+
11+
## Purpose
12+
13+
These specifications ensure:
14+
1. **Consistency**: Both Python and TypeScript SDKs implement the same contract
15+
2. **Validation**: SDKs can validate extension responses
16+
3. **Type Safety**: Strong typing in both languages
17+
4. **Documentation**: Clear reference for developers
18+
19+
## Usage
20+
21+
### For SDK Developers
22+
23+
1. **Read** `SNAPSHOT_V1.md` for human-readable contract
24+
2. **Use** `snapshot.schema.json` for JSON Schema validation
25+
3. **Reference** `sdk-types.md` for SDK-level types
26+
27+
### For Extension Developers
28+
29+
1. **Ensure** extension output matches `snapshot.schema.json`
30+
2. **Update** schema when adding new fields
31+
3. **Version** schema for breaking changes
32+
33+
## Versioning
34+
35+
- **v1.0.0**: Initial stable version (Day 1)
36+
- Future versions: Increment major version for breaking changes
37+
- SDKs should validate version and handle compatibility
38+
39+
## Validation
40+
41+
Both SDKs should validate extension responses:
42+
43+
**Python**:
44+
```python
45+
import jsonschema
46+
from spec.snapshot.schema import load_schema
47+
48+
schema = load_schema()
49+
jsonschema.validate(snapshot_data, schema)
50+
```
51+
52+
**TypeScript**:
53+
```typescript
54+
import Ajv from 'ajv';
55+
import schema from './spec/snapshot.schema.json';
56+
57+
const ajv = new Ajv();
58+
const validate = ajv.compile(schema);
59+
validate(snapshot_data);
60+
```
61+
62+
## Testing
63+
64+
- Validate against real extension output
65+
- Test with edge cases (empty pages, many elements, errors)
66+
- Verify type coercion and defaults
67+
68+
---
69+
70+
**Last Updated**: Day 1 Implementation
71+
**Status**: ✅ Stable
72+

0 commit comments

Comments
 (0)