Add GitHub Packages publishing workflow

.github/workflows/publish-github-packages.yml

@@ -0,0 +1,97 @@
+name: Publish to GitHub Packages
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to publish (without v prefix)'
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 20.x
+        cache: 'npm'
+        registry-url: 'https://npm.pkg.github.com'
+        scope: '@openhands'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Run tests
+      run: npm test
+
+    - name: Build package
+      run: npm run build
+
+    - name: Extract version from tag or input
+      id: version
+      run: |
+        if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+          echo "VERSION=${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT
+        else
+          echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+        fi
+
+    - name: Update package version
+      run: npm version ${{ steps.version.outputs.VERSION }} --no-git-tag-version
+
+    - name: Publish to GitHub Packages
+      run: npm publish --access public
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Create GitHub Release (for tag pushes only)
+      if: github.event_name == 'push'
+      uses: softprops/action-gh-release@v1
+      with:
+        tag_name: ${{ github.ref_name }}
+        name: Release ${{ github.ref_name }}
+        draft: false
+        prerelease: false
+        generate_release_notes: true
+        body: |
+          ## Installation from GitHub Packages
+
+          ```bash
+          npm install @openhands/typescript-client@${{ steps.version.outputs.VERSION }} --registry=https://npm.pkg.github.com
+          ```
+
+          Or add to your `.npmrc`:
+          ```
+          @openhands:registry=https://npm.pkg.github.com
+          ```
+
+          Then install normally:
+          ```bash
+          npm install @openhands/typescript-client@${{ steps.version.outputs.VERSION }}
+          ```
+
+          ## Usage
+
+          ```typescript
+          import { RemoteConversation } from '@openhands/typescript-client';
+
+          const conversation = new RemoteConversation({
+            baseUrl: 'http://localhost:8000',
+            apiKey: 'your-api-key'
+          });
+
+          await conversation.start();
+          ```

.github/workflows/release.yml

@@ -5,6 +5,10 @@ on:
     tags:
       - 'v*'
 
+permissions:
+  contents: write
+  packages: write
+
 jobs:
   release:
     runs-on: ubuntu-latest
@@ -13,12 +17,13 @@ jobs:
     - name: Checkout code
       uses: actions/checkout@v4
 
-    - name: Use Node.js 20.x
+    - name: Setup Node.js for GitHub Packages
       uses: actions/setup-node@v4
       with:
         node-version: 20.x
         cache: 'npm'
-        registry-url: 'https://registry.npmjs.org'
+        registry-url: 'https://npm.pkg.github.com'
+        scope: '@openhands'
 
     - name: Install dependencies
       run: npm ci
@@ -29,27 +34,52 @@ jobs:
     - name: Build package
       run: npm run build
 
-    - name: Publish to npm
+    - name: Extract version from tag
+      id: version
+      run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+    - name: Update package version
+      run: npm version ${{ steps.version.outputs.VERSION }} --no-git-tag-version
+
+    - name: Publish to GitHub Packages
       run: npm publish --access public
       env:
-        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
     - name: Create GitHub Release
-      uses: actions/create-release@v1
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      uses: softprops/action-gh-release@v1
       with:
-        tag_name: ${{ github.ref }}
-        release_name: Release ${{ github.ref }}
+        tag_name: ${{ github.ref_name }}
+        name: Release ${{ github.ref_name }}
         draft: false
         prerelease: false
+        generate_release_notes: true
         body: |
-          ## Changes
+          ## Installation from GitHub Packages
 
-          See [CHANGELOG.md](CHANGELOG.md) for details.
+          ### Option 1: Configure .npmrc (Recommended)
+          Add to your `.npmrc` file:
+          ```
+          @openhands:registry=https://npm.pkg.github.com
+          ```
 
-          ## Installation
+          Then install:
+          ```bash
+          npm install @openhands/typescript-client@${{ steps.version.outputs.VERSION }}
+          ```
 
+          ### Option 2: Direct install with registry flag
           ```bash
-          npm install @openhands/agent-server-typescript-client@${{ github.ref_name }}
+          npm install @openhands/typescript-client@${{ steps.version.outputs.VERSION }} --registry=https://npm.pkg.github.com
+          ```
+
+          ## Usage
+
+          ```typescript
+          import { RemoteConversation } from '@openhands/typescript-client';
+
+          const conversation = new RemoteConversation({
+            baseUrl: 'http://localhost:8000',
+            apiKey: 'your-api-key'
+          });
           ```

.npmrc

@@ -0,0 +1 @@
+@openhands:registry=https://npm.pkg.github.com

PUBLISHING.md

@@ -0,0 +1,105 @@
+# Publishing Guide
+
+This document explains how to publish the OpenHands TypeScript Client to GitHub Packages.
+
+## Overview
+
+The package is published exclusively to **GitHub Packages** for GitHub-native integration.
+
+## Automated Publishing (Recommended)
+
+### Prerequisites
+
+- **GitHub Token**: Automatically provided by GitHub Actions as `GITHUB_TOKEN`
+
+### Publishing Process
+
+1. **Create and push a version tag**:
+   ```bash
+   git tag v1.0.0
+   git push origin v1.0.0
+   ```
+
+2. **The GitHub Action will automatically**:
+   - Run tests
+   - Build the package
+   - Update package.json version
+   - Publish to GitHub Packages
+   - Create a GitHub release with installation instructions
+
+## Manual Publishing
+
+### Setup
+
+1. **Configure npm for GitHub Packages**:
+   ```bash
+   npm login --registry=https://npm.pkg.github.com
+   # Username: your-github-username
+   # Password: your-github-token
+   ```
+
+### Publishing Steps
+
+1. **Update version**:
+   ```bash
+   npm version patch  # or minor, major
+   ```
+
+2. **Build the package**:
+   ```bash
+   npm run build
+   ```
+
+3. **Run tests**:
+   ```bash
+   npm test
+   ```
+
+4. **Publish to GitHub Packages**:
+   ```bash
+   npm publish --registry=https://npm.pkg.github.com --access public
+   ```
+
+## Installation Instructions for Users
+
+### From GitHub Packages
+
+#### Option 1: Configure .npmrc (Recommended)
+Add to your `.npmrc` file:
+```
+@openhands:registry=https://npm.pkg.github.com
+```
+
+Then install:
+```bash
+npm install @openhands/typescript-client
+```
+
+#### Option 2: Direct install with registry flag
+```bash
+npm install @openhands/typescript-client --registry=https://npm.pkg.github.com
+```
+
+## Troubleshooting
+
+### Authentication Issues
+
+- **GitHub Packages**: Ensure the `GITHUB_TOKEN` has `packages:write` permission
+
+### Version Conflicts
+
+If you encounter version conflicts, ensure:
+- The version in `package.json` matches the git tag
+- The version doesn't already exist in the registry
+
+### Build Failures
+
+Common issues:
+- TypeScript compilation errors: Fix in source code
+- Test failures: Ensure all tests pass before publishing
+- Missing dependencies: Run `npm ci` to install exact versions
+
+## Workflow Files
+
+- `.github/workflows/release.yml`: Main release workflow (GitHub Packages)
+- `.github/workflows/publish-github-packages.yml`: GitHub Packages only workflow with manual trigger

README.md

@@ -14,6 +14,26 @@
 A TypeScript client library for the OpenHands Agent Server API. Mirrors the structure and functionality of the Python [OpenHands Software Agent SDK](https://github.com/OpenHands/software-agent-sdk),
 but only supports remote conversations.
 
+## Installation
+
+This package is published to GitHub Packages. You have two installation options:
+
+### Option 1: Configure .npmrc (Recommended)
+Add this to your `.npmrc` file:
+```
+@openhands:registry=https://npm.pkg.github.com
+```
+
+Then install normally:
+```bash
+npm install @openhands/typescript-client
+```
+
+### Option 2: Direct install with registry flag
+```bash
+npm install @openhands/typescript-client --registry=https://npm.pkg.github.com
+```
+
 ## Quick Start
 
 ### Start an AgentServer
@@ -29,7 +49,7 @@ docker run -p 8000:8000 -p 8001:8001 \
 ### Creating a Conversation
 
 ```typescript
-import { Conversation, Agent, Workspace } from '@openhands/agent-server-typescript-client';
+import { Conversation, Agent, Workspace } from '@openhands/typescript-client';
 
 const agent = new Agent({
   llm: {
@@ -242,7 +262,7 @@ The library includes comprehensive TypeScript type definitions:
 The client includes proper error handling with custom error types:
 
 ```typescript
-import { HttpError } from '@openhands/agent-server-typescript-client';
+import { HttpError } from '@openhands/typescript-client';
 
 try {
   await conversation.sendMessage('Hello');

package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@openhands/agent-server-typescript-client",
+  "name": "@openhands/typescript-client",
   "version": "0.1.0",
   "description": "TypeScript client for OpenHands Agent Server",
   "main": "dist/index.js",
@@ -50,6 +50,6 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/All-Hands-AI/agent-server-typescript-client.git"
+    "url": "https://github.com/OpenHands/typescript-client.git"
   }
 }