feat(adapters-internal): implement FirestoreAdapter with retry logic

.github/workflows/release.yml

@@ -45,14 +45,37 @@ jobs:
       - name: Build Packages
         run: pnpm build
 
-      - name: Create Release Pull Request or Publish to npm
+      # Configure npm/pnpm for GitHub Packages (for internal packages)
+      # Create .npmrc with GitHub Packages authentication before changesets runs
+      - name: Configure GitHub Packages authentication
+        run: |
+          # Create .npmrc in project root with GitHub Packages config
+          # This will be read by pnpm and changesets
+          cat > .npmrc << EOF
+          @lytics:registry=https://npm.pkg.github.com
+          //npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}
+          EOF
+          # Also create in home directory for npm (changesets might create its own, but this ensures auth is available)
+          mkdir -p ~/.npm
+          cat > ~/.npmrc << EOF
+          @lytics:registry=https://npm.pkg.github.com
+          //npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}
+          EOF
+          # Verify configuration
+          echo "Project .npmrc:"
+          cat .npmrc
+          echo "User .npmrc:"
+          cat ~/.npmrc
+
+      - name: Create Release Pull Request or Publish to npm/GitHub Packages
         id: changesets
         uses: changesets/action@v1
         with:
           # This creates a "Version Packages" PR when changesets are added
           version: pnpm changeset version
-          # This publishes to npm when the version PR is merged
-          # Uses OIDC trusted publishing - no NPM_TOKEN needed!
+          # This publishes to npm (public packages) or GitHub Packages (internal packages)
+          # Public packages use OIDC trusted publishing (no NPM_TOKEN needed)
+          # Internal packages use GITHUB_TOKEN for GitHub Packages via .npmrc
           publish: pnpm changeset publish
           # Commit message for version bumps
           commit: 'chore: release packages'
@@ -62,4 +85,5 @@ jobs:
           createGithubReleases: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # No NPM_TOKEN needed - OIDC handles authentication!
+          # No NPM_TOKEN needed - OIDC handles npm authentication!
+          # GITHUB_TOKEN is used via .npmrc for GitHub Packages authentication

README.md

@@ -76,6 +76,7 @@ test.describe("My Feature @smoke", () => {
 - [Getting Started Guide](./docs/getting-started.md)
 - [Annotations Guide](./docs/annotations-guide.md)
 - [Adapters Guide](./docs/adapters-guide.md)
+- [Release Process](./docs/RELEASE_PROCESS.md)
 - [Journey Guide](./docs/journey-guide.md) (Internal)
 
 ## 🏗️ Architecture
@@ -149,20 +150,16 @@ pnpm typecheck
 
 ### Publishing
 
-This monorepo uses [Changesets](https://github.com/changesets/changesets) for version management:
+This monorepo uses [Changesets](https://github.com/changesets/changesets) for version management. See [RELEASE_PROCESS.md](./docs/RELEASE_PROCESS.md) for details.
 
-```bash
-# 1. Make your changes
-
-# 2. Create a changeset
-pnpm changeset
+**Quick overview:**
+1. Make your changes
+2. Create a changeset: `pnpm changeset`
+3. Commit and push
+4. CI creates a release PR
+5. Merge the PR to publish
 
-# 3. Commit changes
-git commit -m "feat: add new feature"
-
-# 4. CI will create a release PR
-# 5. Merge the release PR to publish
-```
+Public packages publish to npm, internal packages publish to GitHub Packages automatically.
 
 ## 🤝 Contributing
 

docs/RELEASE_PROCESS.md

@@ -0,0 +1,118 @@
+# Release Process
+
+This document explains how packages are released in this monorepo.
+
+## Overview
+
+This repository uses [Changesets](https://github.com/changesets/changesets) for version management and automated releases. Packages are published to different registries based on their configuration:
+
+- **Public packages** → Published to [npm](https://www.npmjs.com/)
+- **Internal packages** → Published to [GitHub Packages](https://github.com/features/packages)
+
+## How Releases Work
+
+### 1. Create a Changeset
+
+After making changes and merging your PR:
+
+```bash
+pnpm changeset
+```
+
+Follow the prompts:
+- Select which packages changed
+- Choose version bump (patch/minor/major)
+- Write a summary of changes
+
+### 2. Commit and Push
+
+```bash
+git add .changeset/
+git commit -m "chore: add changeset"
+git push
+```
+
+### 3. Release PR Created
+
+The Changesets bot automatically creates a PR titled "chore: release packages" with:
+- Updated version numbers
+- Updated changelogs
+- List of packages to publish
+
+### 4. Review and Merge
+
+Review the version changes, then merge the PR. The release workflow will:
+- Publish public packages to npm
+- Publish internal packages to GitHub Packages
+- Create GitHub Releases
+
+## Package Configuration
+
+### Public Packages (npm)
+
+Packages without `publishConfig` are published to npm:
+
+```json
+{
+  "name": "@lytics/playwright-annotations",
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+### Internal Packages (GitHub Packages)
+
+Packages with `registry` configured are published to GitHub Packages:
+
+```json
+{
+  "name": "@lytics/playwright-adapters-internal",
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com",
+    "access": "restricted"
+  }
+}
+```
+
+## Installing Internal Packages
+
+To install packages from GitHub Packages, configure npm authentication:
+
+### Option 1: Using GITHUB_TOKEN (CI/CD)
+
+```bash
+# In your CI/CD environment
+echo "@lytics:registry=https://npm.pkg.github.com" >> .npmrc
+echo "//npm.pkg.github.com/:_authToken=$GITHUB_TOKEN" >> .npmrc
+```
+
+### Option 2: Using Personal Access Token (Local)
+
+Create `.npmrc` in your project:
+
+```
+@lytics:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=YOUR_PERSONAL_ACCESS_TOKEN
+```
+
+**Note:** Add `.npmrc` to `.gitignore` if it contains tokens!
+
+Then install:
+
+```bash
+npm install @lytics/playwright-adapters-internal
+```
+
+## Versioning Guidelines
+
+- **Patch** (`0.1.0` → `0.1.1`): Bug fixes, small improvements
+- **Minor** (`0.1.0` → `0.2.0`): New features, backward compatible
+- **Major** (`0.1.0` → `1.0.0`): Breaking changes
+
+## Questions?
+
+- See [Changesets documentation](https://github.com/changesets/changesets)
+- Check the [Release workflow](.github/workflows/release.yml)
+- Open an [issue](https://github.com/lytics/playwright-core/issues) for questions
+