add specs

.github/workflows/release.yml

@@ -0,0 +1,85 @@
+name: Release to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release (e.g., 0.1.0)'
+        required: true
+        type: string
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        registry-url: 'https://registry.npmjs.org'
+
+    - name: Extract version from tag or input
+      id: version
+      run: |
+        if [ "${{ github.event_name }}" == "release" ]; then
+          VERSION=${GITHUB_REF#refs/tags/v}
+          VERSION=${VERSION#refs/tags/}
+        else
+          VERSION="${{ github.event.inputs.version }}"
+        fi
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+        echo "Version: $VERSION"
+
+    - name: Update version in package.json
+      run: |
+        VERSION="${{ steps.version.outputs.version }}"
+        npm version $VERSION --no-git-tag-version
+
+    - name: Install dependencies
+      run: |
+        npm ci
+
+    - name: Install Playwright browsers
+      run: |
+        npx playwright install chromium
+
+    - name: Run tests
+      run: |
+        npm test
+      env:
+        CI: true
+
+    - name: Build package
+      run: |
+        npm run build
+
+    - name: Publish to npm
+      run: |
+        npm publish --access public
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+    - name: Create GitHub Release
+      if: github.event_name == 'workflow_dispatch'
+      uses: softprops/action-gh-release@v1
+      with:
+        tag_name: v${{ steps.version.outputs.version }}
+        name: Release v${{ steps.version.outputs.version }}
+        body: |
+          Release v${{ steps.version.outputs.version }} of sentience-ts
+
+          ## Installation
+          ```bash
+          npm install sentience-ts@${{ steps.version.outputs.version }}
+          ```
+        draft: false
+        prerelease: false
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+

.github/workflows/test.yml

@@ -0,0 +1,51 @@
+name: Test
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node-version: ['20']
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+
+    - name: Install dependencies
+      run: |
+        npm ci --ignore-scripts
+
+    - name: Build package
+      run: |
+        npm run build
+
+    - name: Install Playwright browsers
+      run: |
+        npx playwright install chromium
+
+    - name: Build extension (if needed)
+      run: |
+        if [ -d "../sentience-chrome" ]; then
+          cd ../sentience-chrome && ./build.sh || echo "Extension build skipped (may not be available in CI)"
+        else
+          echo "Extension directory not found, skipping build"
+        fi
+
+    - name: Run tests
+      run: |
+        npm test
+      env:
+        CI: true
+

.npmignore

@@ -0,0 +1,45 @@
+# Source files
+src/
+examples/
+tests/
+*.ts
+!*.d.ts
+
+# Build artifacts (keep dist/)
+*.map
+*.js.map
+*.d.ts.map
+
+# Development files
+.git/
+.github/
+node_modules/
+*.log
+.DS_Store
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Test files
+coverage/
+.nyc_output/
+jest.config.js
+tsconfig.json
+
+# Documentation (keep README.md)
+docs/
+*.md
+!README.md
+
+# CI/CD
+.github/
+
+# Temporary files
+*.tmp
+*.temp
+

package.json

@@ -7,6 +7,8 @@
   "scripts": {
     "build": "tsc",
     "test": "jest",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm test && npm run build",
     "example:hello": "ts-node examples/hello.ts",
     "example:basic": "ts-node examples/basic-agent.ts",
     "cli": "ts-node src/cli.ts"
@@ -25,5 +27,30 @@
     "ts-jest": "^29.0.0",
     "ts-node": "^10.9.0",
     "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "spec",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "browser-automation",
+    "playwright",
+    "ai-agent",
+    "web-automation",
+    "sentience"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SentienceAPI/sentience-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SentienceAPI/sentience-ts/issues"
+  },
+  "homepage": "https://github.com/SentienceAPI/sentience-ts#readme",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
   }
 }

spec/README.md

@@ -0,0 +1,72 @@
+# Sentience API Specification
+
+This directory contains the **single source of truth** for the API contract between the Chrome extension and SDKs.
+
+## Files
+
+- **`snapshot.schema.json`** - JSON Schema for snapshot response validation
+- **`SNAPSHOT_V1.md`** - Human-readable snapshot API contract
+- **`sdk-types.md`** - SDK-level type definitions (ActionResult, WaitResult, TraceStep)
+
+## Purpose
+
+These specifications ensure:
+1. **Consistency**: Both Python and TypeScript SDKs implement the same contract
+2. **Validation**: SDKs can validate extension responses
+3. **Type Safety**: Strong typing in both languages
+4. **Documentation**: Clear reference for developers
+
+## Usage
+
+### For SDK Developers
+
+1. **Read** `SNAPSHOT_V1.md` for human-readable contract
+2. **Use** `snapshot.schema.json` for JSON Schema validation
+3. **Reference** `sdk-types.md` for SDK-level types
+
+### For Extension Developers
+
+1. **Ensure** extension output matches `snapshot.schema.json`
+2. **Update** schema when adding new fields
+3. **Version** schema for breaking changes
+
+## Versioning
+
+- **v1.0.0**: Initial stable version (Day 1)
+- Future versions: Increment major version for breaking changes
+- SDKs should validate version and handle compatibility
+
+## Validation
+
+Both SDKs should validate extension responses:
+
+**Python**:
+```python
+import jsonschema
+from spec.snapshot.schema import load_schema
+
+schema = load_schema()
+jsonschema.validate(snapshot_data, schema)
+```
+
+**TypeScript**:
+```typescript
+import Ajv from 'ajv';
+import schema from './spec/snapshot.schema.json';
+
+const ajv = new Ajv();
+const validate = ajv.compile(schema);
+validate(snapshot_data);
+```
+
+## Testing
+
+- Validate against real extension output
+- Test with edge cases (empty pages, many elements, errors)
+- Verify type coercion and defaults
+
+---
+
+**Last Updated**: Day 1 Implementation  
+**Status**: ✅ Stable
+