Permify · omer-topal · Apr 16, 2026 · Apr 16, 2026 · Apr 16, 2026
diff --git a/.github/workflows/generator.yml b/.github/workflows/generator.yml
@@ -0,0 +1,73 @@
+name: Update Permify JavaScript SDK
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  generate:
+    name: Generate SDK from OpenAPI
+    timeout-minutes: 15
+    runs-on: ubuntu-latest
+
+    steps:
+      # Security hardening for GitHub Actions runner
+      - name: Harden Runner
+        uses: step-security/harden-runner@df199fb7be9f65074067a9eb93f12bb4c5547cf2 # v2.13.3
+        with:
+          egress-policy: audit
+
+      # Checkout the current repository
+      - name: Checkout Repository
+        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+
+      # Download the latest OpenAPI spec from the Permify repository
+      - name: Download OpenAPI Spec
+        run: |
+          curl -fsSL "https://raw.githubusercontent.com/Permify/permify/master/docs/api-reference/openapiv2/apidocs.swagger.json" \
+            -o generator/openapi.json
+
+      # Setup Java (required for openapi-generator-cli)
+      - name: Setup Java
+        uses: actions/setup-java@3a4f6e1af504cf6a31855fa899c6aa5e40ceef53 # v4.7.0
+        with:
+          distribution: temurin
+          java-version: 17
+
+      # Generate the SDK
+      - name: Generate JavaScript SDK
+        run: |
+          chmod +x generator/generate-sdk.sh
+          generator/generate-sdk.sh
+
+      # Commit changes and open PR if there are changes
+      - name: Commit changes
+        id: commitchanges
+        run: |
+          chmod +x scripts/commit-changes.sh
+          scripts/commit-changes.sh "sdk-update/permify-latest"
+        shell: bash
+
+      # Push branch and open or update the PR only if there are changes
+      - name: Push changes and open PR
+        if: steps.commitchanges.outputs.changes_made == '1'
+        env:
+          GH_TOKEN: ${{ secrets.PAT_TOKEN }}
+        run: |
+          BRANCH_NAME="${{ steps.commitchanges.outputs.branch_name }}"
+          PR_TITLE="chore(openapi): update generated SDK with latest Permify definitions"
+          PR_BODY="Automatically created PR with the latest generated SDK from Permify OpenAPI definitions."
+
+          git push --force "https://x-access-token:${{ secrets.PAT_TOKEN }}@github.com/${{ github.repository }}" "${BRANCH_NAME}"
+
+          PR_NUMBER="$(gh pr list --head "${BRANCH_NAME}" --base main --state open --json number --jq '.[0].number')"
+
+          if [ -n "${PR_NUMBER}" ]; then
+            gh pr edit "${PR_NUMBER}" --title "${PR_TITLE}" --body "${PR_BODY}"
+          else
+            gh pr create --base main --head "${BRANCH_NAME}" --title "${PR_TITLE}" --body "${PR_BODY}" --label dependencies --label automated
+          fi
+        shell: bash
diff --git a/.github/workflows/npm-publish.yml b/.github/workflows/npm-publish.yml
@@ -1,57 +1,49 @@
-name: Js Sdk Package
+name: Publish to NPM
 
 on:
-  push:
-    branches:
-      - main
+  release:
+    types:
+      - published
+
+permissions:
+  contents: read
 
 jobs:
-  update-package-json:
+  publish:
+    name: Publish to NPM
+    timeout-minutes: 10
     runs-on: ubuntu-latest
+
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v3
+      # Security hardening for GitHub Actions runner
+      - name: Harden Runner
+        uses: step-security/harden-runner@df199fb7be9f65074067a9eb93f12bb4c5547cf2 # v2.13.3
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+
+      - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
         with:
-          node-version: 16
-      - run: |
-          node -e "
-          const fs = require('fs');
-          const { execSync } = require('child_process');
-          const path = './package.json';
-          const pkg = require(path);
-          const repo = process.env.GITHUB_REPOSITORY.split('/')[1];
-          pkg.name = repo;
-          try {
-            const latestVersion = execSync('npm view ' + repo + ' version').toString().trim();
-            const versionParts = latestVersion.split('.');
-            versionParts[2] = (parseInt(versionParts[2]) + 1).toString();
-            pkg.version = versionParts.join('.');
-          } catch (error) {
-            console.error('Error fetching latest version:', error);
-            pkg.version = '1.0.0';
-          }
-          fs.writeFileSync(path, JSON.stringify(pkg, null, 2));
-          console.log('Updated name:', pkg.name);
-          console.log('Updated version:', pkg.version);
-          "
-      - run: |
-          echo "Name and version from package.json:"
-          cat package.json | jq '.name, .version'
-      - run: |
-          if [ -f package-lock.json ]; then
-            npm ci
-          else
-            npm install
-          fi
-      - run: npm test
-      - run: |
-          if [ -f package-lock.json ]; then
-            npm ci
-          else
-            npm install
-          fi
-      - run: |
-          echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > .npmrc
-      - run: npm publish
+          node-version: 20
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build
+        run: npm run build
+
+      - name: Write release version
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          echo Version: $VERSION
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+
+      - name: Set version
+        run: npm version ${VERSION} --no-git-tag-version --allow-same-version
+
+      - name: Publish to NPM
+        run: npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/RELEASE.md b/RELEASE.md
@@ -0,0 +1,165 @@
+# Release Process
+
+This document explains how to release a new version of `permify-javascript` to NPM.
+
+## Overview
+
+The release process is fully automated using GitHub Actions. When you create a GitHub release, the package is automatically published to NPM.
+
+## How to Release
+
+### 1. Prepare
+
+Make sure everything is ready:
+
+```bash
+# Pull latest changes
+git checkout main
+git pull origin main
+
+# Install dependencies and build
+npm install
+npm run build
+```
+
+### 2. Choose Version Number
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (x.0.0) - Breaking changes
+- **MINOR** (0.x.0) - New features (backward compatible)
+- **PATCH** (0.0.x) - Bug fixes
+
+Examples:
+- `0.11.1` → `0.11.2` (bug fix)
+- `0.11.2` → `0.12.0` (new feature)
+- `0.12.0` → `1.0.0` (breaking change)
+
+### 3. Create GitHub Release
+
+1. Go to [Releases](https://github.com/Permify/permify-javascript/releases)
+2. Click **"Draft a new release"**
+3. Fill in the details:
+   - **Tag version**: `v0.12.0` (must start with `v`)
+   - **Release title**: `v0.12.0`
+   - **Description**: List changes, new features, and bug fixes
+4. Click **"Publish release"**
+
+### 4. Automatic Publishing
+
+Once published, GitHub Actions will:
+- Build the package
+- Extract version from tag (e.g., `v0.12.0` → `0.12.0`)
+- Update `package.json` version
+- Publish to NPM
+
+Track progress at: https://github.com/Permify/permify-javascript/actions
+
+### 5. Verify
+
+Check that the new version is live:
+
+```bash
+npm view permify-javascript version
+```
+
+## SDK Updates
+
+The JavaScript SDK is automatically regenerated from the [Permify OpenAPI spec](https://github.com/Permify/permify/blob/master/docs/api-reference/openapiv2/apidocs.swagger.json) whenever Permify publishes a new release.
+
+### Automatic Updates
+
+The generator workflow (`generator.yml`) is dispatched by the main Permify repo on each release:
+- Downloads the latest OpenAPI spec
+- Regenerates the JavaScript SDK using `openapi-generator-cli`
+- Creates a pull request if changes are detected
+- PR branch: `sdk-update/permify-latest`
+
+### Manual Update
+
+To manually regenerate the SDK:
+
+1. Go to [Actions](https://github.com/Permify/permify-javascript/actions)
+2. Select **"Update Permify JavaScript SDK"**
+3. Click **"Run workflow"**
+
+Or locally:
+
+```bash
+# Download the latest OpenAPI spec
+curl -fsSL https://raw.githubusercontent.com/Permify/permify/master/docs/api-reference/openapiv2/apidocs.swagger.json \
+  -o generator/openapi.json
+
+# Run the generator
+./generator/generate-sdk.sh
+```
+
+## Configuration
+
+### Required Secrets
+
+Set in GitHub repository settings:
+
+- **NPM_TOKEN**: Authentication token for publishing to NPM
+  - Create at [npmjs.com](https://www.npmjs.com/) → Access Tokens
+  - Type: **Granular Access Token**
+  - Permission: **Read and Write**, bypass 2FA enabled
+
+- **PAT_TOKEN**: Personal Access Token for opening pull requests
+  - Create at GitHub → Settings → Developer settings → Personal access tokens
+  - Scopes: `repo`, `workflow`
+
+## Workflows
+
+### 1. Publish Workflow (`.github/workflows/npm-publish.yml`)
+
+**Trigger**: GitHub release published
+
+**Steps**:
+1. Checkout code
+2. Setup Node.js 20
+3. Install dependencies
+4. Build (`npm run build`)
+5. Update version from release tag
+6. Publish to NPM
+
+### 2. SDK Generator Workflow (`.github/workflows/generator.yml`)
+
+**Trigger**: Dispatched from Permify main repo or manual dispatch
+
+**Steps**:
+1. Download latest OpenAPI spec from Permify
+2. Setup Java (required for openapi-generator-cli)
+3. Run `generator/generate-sdk.sh`
+4. Create PR if changes detected
+
+## Troubleshooting
+
+### Build Failed
+
+```bash
+# Test locally
+npm install
+npm run build
+```
+
+### Publish Failed
+
+- Check if `NPM_TOKEN` is valid and owned by an npm account that has publish access
+- Verify version doesn't already exist on NPM: `npm view permify-javascript versions`
+- Check [Actions logs](https://github.com/Permify/permify-javascript/actions)
+
+### Wrong Version Published
+
+If you published the wrong version:
+
+1. Delete the GitHub release
+2. Delete the Git tag:
+   ```bash
+   git tag -d v0.12.0
+   git push origin :refs/tags/v0.12.0
+   ```
+3. Unpublish from NPM (within 24 hours):
+   ```bash
+   npm unpublish permify-javascript@0.12.0
+   ```
diff --git a/generator/generate-sdk.sh b/generator/generate-sdk.sh
@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${SCRIPT_DIR}/.."
+OPENAPI_FILE="${SCRIPT_DIR}/openapi.json"
+GENERATOR_VERSION="7.13.0"
+PACKAGE_VERSION="$(sed -n 's/^[[:space:]]*"version":[[:space:]]*"\([^"]*\)".*/\1/p' "${PROJECT_ROOT}/package.json" | head -n 1)"
+
+if [[ -z "${PACKAGE_VERSION}" ]]; then
+  echo "Could not determine package version from ${PROJECT_ROOT}/package.json" >&2
+  exit 1
+fi
+
+echo "Downloading openapi-generator-cli..."
+curl -fsSL "https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/${GENERATOR_VERSION}/openapi-generator-cli-${GENERATOR_VERSION}.jar" \
+  -o "${SCRIPT_DIR}/openapi-generator-cli.jar"
+
+echo "Generating JavaScript SDK..."
+java -jar "${SCRIPT_DIR}/openapi-generator-cli.jar" generate \
+  --input-spec "${OPENAPI_FILE}" \
+  --generator-name javascript \
+  --output "${PROJECT_ROOT}" \
+  --additional-properties \
+    moduleName=PermifyClient,\
+    projectName=permify-javascript,\
+    projectVersion="${PACKAGE_VERSION}",\
+    licenseName=Apache-2.0,\
+    usePromises=true,\
+    useES6=true \
+  --global-property modelDocs=true,apiDocs=true \
+  --skip-validate-spec
+
+rm -f "${SCRIPT_DIR}/openapi-generator-cli.jar"
+
+echo "Generation complete."
diff --git a/package.json b/package.json
@@ -1,8 +1,8 @@
 {
   "name": "permify-javascript",
-  "version": "v0.11.0",
+  "version": "0.11.0",
   "description": "Permify is an open source authorization service for creating fine-grained and scalable authorization systems.",
-  "license": "Apache-2.0 license",
+  "license": "Apache-2.0",
   "main": "dist/index.js",
   "scripts": {
     "build": "babel src -d dist",