@powergym/auth-sdk

PowerGym auth SDK for React (and other) apps: login URL, token storage, refresh, and API headers.

Install

# From npm (recommended)
yarn add @powergym/auth-sdk
# or
npm install @powergym/auth-sdk

Setup

Call initAuthSdk() once at app bootstrap (e.g. in your root component or auth provider), before using any other SDK functions.

import { initAuthSdk } from "@powergym/auth-sdk";

// Example: localStorage adapter
const storage = {
  getItem<T>(key: string): T | null {
    try {
      const item = localStorage.getItem(key);
      return item ? (JSON.parse(item) as T) : null;
    } catch {
      return null;
    }
  },
  setItem<T>(key: string, value: T) {
    try {
      localStorage.setItem(key, JSON.stringify(value));
    } catch {
      // ignore
    }
  },
};

initAuthSdk({
  storage,
  authServiceUrl: import.meta.env.VITE_AUTH_SERVICE_URL ?? "",
  isReturnUrlAllowed: (returnUrl) => {
    try {
      const u = new URL(returnUrl);
      if (u.protocol !== "https:") return false;
      return (
        u.hostname === "myapp.com" ||
        u.hostname.endsWith(".myapp.com")
      );
    } catch {
      return false;
    }
  },
  applyHeaders: (headers) => {
    if (headers === null) {
      delete http.defaults.headers.common.Authorization;
      delete http.defaults.headers.common["X-Tenant-Id"];
    } else {
      Object.assign(http.defaults.headers.common, headers);
    }
  },
});

API

• initAuthSdk(config) — Initialize the SDK (required once).
• getLoginUrl(returnUrl) — Build login URL with return_url query.
• parseAuthFromUrl() — Read token, refresh_token, tenant_id from hash and clean URL.
• buildAuthTokensFromRedirect(token, refreshToken, tenantId) — Build AuthTokens from redirect params.
• getToken(), getTenantId(), getRefreshToken(), getStoredTokens(), clearStoredTokens() — Read/clear storage.
• createApiHeaders() — { Authorization, "X-Tenant-Id" } for API calls.
• refreshTokensAgainstAS() — Refresh and persist tokens; calls applyHeaders if set.
• isReturnUrlAllowed(returnUrl) — Validate return URL for redirects.

Types

• AuthTokens — accessToken, refreshToken, tokenType, accessTokenExpiresAt, refreshTokenExpiresAt?, tenantId?
• ParsedAuthFromUrl — token, refresh_token, tenant_id (all required)
• AuthStorage — getItem<T>, setItem<T>, optional removeItem
• AuthSdkConfig — storage, authServiceUrl, isReturnUrlAllowed, optional applyHeaders
• IsReturnUrlAllowedFn — (returnUrl: string) => boolean for validating redirect URLs

Build

yarn install
yarn build

Output: dist/ (ESM + .d.ts).

Publishing (maintainers)

1. Create an npm account if needed.
2. In this repo: npm login (use your npm user and token/password).
3. Bump version: npm version patch (or minor / major).
4. Publish: npm publish (build runs automatically via prepublishOnly).

The package is published as public (scoped packages require --access public, already set in publishConfig).