@eminuckan/spine 0.2.2 → 0.3.0

package/docs/architecture.md

@@ -0,0 +1,193 @@
+# Architecture
+
+This document describes how Spine is structured and where each kind of logic should live.
+
+## Goals
+
+Spine tries to solve a common problem in internal platform code:
+
+- product A builds infrastructure
+- product B copies it
+- product C forks the copy
+- shared behavior starts drifting
+
+Spine centralizes the reusable layer while keeping enough extension points for app-specific behavior.
+
+## Layer Model
+
+Spine is organized into three layers:
+
+1. Core primitives
+2. Framework adapters
+3. Application adapters
+
+### 1. Core Primitives
+
+Core primitives should:
+
+- avoid framework-specific response helpers
+- use standard Web `Request` and `Response` APIs
+- expose configuration points for backend conventions
+- stay reusable across multiple apps
+
+Examples:
+
+- token refresh
+- session handling
+- tenant cookie helpers
+- identity cache
+- permission checking
+- API client configuration
+
+### 2. Framework Adapters
+
+Framework adapters make core primitives ergonomic in a specific framework.
+
+Examples:
+
+- `@eminuckan/spine/react-router`
+- `@eminuckan/spine/react-router/server`
+
+Today the React Router adapter is intentionally thin. That is a feature, not a gap: it keeps the core honest and leaves room for future adapters such as Next.js.
+
+### 3. Application Adapters
+
+Application adapters belong in the consuming app and translate Spine into product policy.
+
+Examples:
+
+- setup route redirects
+- entitlement gating
+- domain-specific permission constants
+- generated backend API clients
+- UI wrappers around generic hooks
+
+## Module Responsibilities
+
+### Auth
+
+Owns:
+
+- login
+- callback handling
+- logout
+- token refresh
+- Redis-backed session and OAuth state
+- generic route protection primitives
+
+Does not own:
+
+- product-specific post-login routing
+- setup flow decisions
+
+### Tenant
+
+Owns:
+
+- tenant cookie primitives
+- current tenant resolution
+- available tenant resolution
+- tenant client store and provider
+- membership-aware tenant state
+
+Does not own:
+
+- product-specific no-tenant redirects
+- tenant provisioning flows
+
+### Identity
+
+Owns:
+
+- identity context caching
+- permission fetch orchestration
+- transformation from identity context to tenant-aware user info
+- client identity store and provider
+
+Does not own:
+
+- backend DTO generation
+- product-specific setup data semantics beyond generic fields
+
+### Permissions
+
+Owns:
+
+- client permission store
+- permission hooks
+- generic permission components
+- generic server-side permission route protection
+
+Does not own:
+
+- your product's permission vocabulary
+- domain-specific permission constants
+
+### API Client
+
+Owns:
+
+- base URL and header composition
+- auth header injection
+- tenant header injection
+- fetch middleware
+- retry and error handling
+
+Does not own:
+
+- generated SDK clients
+- product-specific endpoint wrappers
+
+## Composition Pattern
+
+Spine prefers configuration and composition over inheritance or deep factories.
+
+The pattern is:
+
+1. Core exposes a generic primitive
+2. App provides fetchers, endpoint conventions, or redirect policies
+3. App re-exports a thin local adapter if it wants ergonomic imports
+
+This keeps the public API reusable without forcing all apps into the same workflow.
+
+## Where New Code Should Go
+
+Use this checklist before adding a new primitive.
+
+### Put it in Core if
+
+- it solves a repeated platform problem
+- it can be configured instead of hardcoded
+- it does not depend on a single app's domain
+- it can be explained without referencing a product name
+
+### Put it in a Framework Adapter if
+
+- it depends on framework routing or request conventions
+- it is still reusable across many apps using that framework
+
+### Keep it in the App if
+
+- it encodes product policy
+- it references app-only routes
+- it assumes app-only claims, plans, or workflows
+- it is mostly a domain-specific convenience layer
+
+## Current Tradeoffs
+
+Spine is already framework-agnostic at the request/response level, but not every module is maximally abstract yet. Some modules still use environment-driven configuration where factory-based configuration may eventually be better.
+
+That is acceptable as long as:
+
+- the surface remains reusable
+- product logic stays outside core
+- adapters remain thin
+
+## Future Adapter Direction
+
+The intended path is:
+
+- keep root package framework-agnostic
+- keep adapter packages shallow
+- let apps build local adapters for product policy
+- eventually add first-class Next.js support without changing the core mental model

package/docs/backend-adaptation.md

@@ -0,0 +1,249 @@
+# Backend Adaptation
+
+Spine should adapt to your backend, not force your backend to look like the original app it came from.
+
+This guide covers the main extension points.
+
+## Adaptation Categories
+
+There are four major kinds of backend adaptation:
+
+1. Auth claims
+2. Identity endpoints
+3. Permission resolution
+4. Tenant conventions
+
+## Auth Claim Mapping
+
+Use `configureAuthClaimMapping` when your identity provider uses different claim names.
+
+```ts
+import { configureAuthClaimMapping } from '@eminuckan/spine/server';
+
+configureAuthClaimMapping({
+  subject: ['sub', 'user_id'],
+  email: ['email', 'preferred_username'],
+  givenName: ['given_name', 'first_name'],
+  familyName: ['family_name', 'last_name'],
+  permissions: ['permissions', 'scope'],
+  tenantIds: ['tenant_ids'],
+  tenantRoles: ['tenant_roles'],
+  isOnboarded: ['is_onboarded', 'profile_complete'],
+});
+```
+
+## Identity API Fetching
+
+Use `configureIdentityAPIFetcher` to tell Spine how to fetch the current identity context.
+
+```ts
+import { configureIdentityAPIFetcher } from '@eminuckan/spine/identity/server';
+
+configureIdentityAPIFetcher(async (request) => {
+  const response = await fetch('https://api.example.com/me/context', {
+    headers: {
+      Authorization: request.headers.get('Authorization') ?? '',
+    },
+  });
+
+  const payload = await response.json();
+
+  return {
+    userId: payload.user.id,
+    email: payload.user.email,
+    memberships: payload.memberships,
+    hasAnyMembership: payload.memberships.length > 0,
+    isOnboarded: payload.flags.isOnboarded,
+    hasEntitlement: payload.flags.hasEntitlement,
+    contextVersion: payload.version,
+  };
+});
+```
+
+## Permission Fetching
+
+Use `configurePermissionFetcher` when permissions are loaded separately from identity context.
+
+```ts
+import { configurePermissionFetcher } from '@eminuckan/spine/identity/server';
+
+configurePermissionFetcher(async (request, tenantId) => {
+  const response = await fetch(`https://api.example.com/tenants/${tenantId}/permissions`, {
+    headers: {
+      Authorization: request.headers.get('Authorization') ?? '',
+    },
+  });
+
+  const payload = await response.json();
+  return payload.permissions;
+});
+```
+
+## Client Identity Store
+
+Simple apps can configure endpoint paths for browser-side identity refresh.
+
+```ts
+import { configureIdentityStore } from '@eminuckan/spine/identity';
+
+configureIdentityStore({
+  contextEndpoint: '/api/me/context',
+  permissionsEndpoint: '/api/me/permissions',
+  logoutPath: '/session/logout',
+});
+```
+
+Apps with different response contracts can own the fetch and mapping logic.
+
+```ts
+configureIdentityStore({
+  fetchContext: async () => {
+    const response = await fetch('/session/me');
+    const payload = await response.json();
+
+    return {
+      userId: payload.account.id,
+      email: payload.account.email,
+      memberships: payload.workspaces.map((workspace) => ({
+        tenantId: workspace.id,
+        tenantName: workspace.name,
+      })),
+    };
+  },
+  fetchPermissions: async () => {
+    const response = await fetch('/session/capabilities');
+    const payload = await response.json();
+    return payload.capabilities;
+  },
+  onUnauthorized: ({ logoutPath }) => {
+    window.location.assign(`${logoutPath}?reason=expired`);
+  },
+});
+```
+
+## Tenant Cookie Policy
+
+Use `configureTenantCookie` to match your app's cookie requirements.
+
+```ts
+import { configureTenantCookie } from '@eminuckan/spine/tenant/server';
+
+configureTenantCookie({
+  name: '__app_tenant',
+  httpOnly: false,
+  sameSite: 'Lax',
+  path: '/',
+  secure: process.env.NODE_ENV === 'production',
+});
+```
+
+This is especially useful when:
+
+- the tenant cookie must be client-readable
+- the cookie name differs across products
+- secure/samesite behavior varies by deployment model
+
+## Tenant Resolution
+
+Use `configureTenantResolution` so tenant helpers can derive tenant state from any identity context shape.
+
+```ts
+import { configureTenantResolution } from '@eminuckan/spine/tenant/server';
+import { fetchIdentityContext } from './identity.server';
+
+configureTenantResolution({
+  identityContextFetcher: fetchIdentityContext,
+  resolveInitialTenant: ({ identityContext }) => {
+    return identityContext?.workspaces?.[0]?.workspaceId ?? null;
+  },
+  resolveAvailableTenants: ({ identityContext }) => {
+    return identityContext?.workspaces?.map((workspace) => workspace.workspaceId) ?? [];
+  },
+});
+```
+
+The older `configureIdentityContextFetcher` helper remains available for simple
+identity contexts that already expose `memberships[].tenantId`.
+
+## Route Protection Policy
+
+Use `configureRouteProtection` for product-specific route policy that still belongs close to auth.
+
+```ts
+import { configureRouteProtection } from '@eminuckan/spine/server';
+
+configureRouteProtection({
+  getLoginReturnUrl: ({ request }) => new URL(request.url).pathname,
+  resolveRoute: async ({ protection, getIdentityContext }) => {
+    const identityContext = await getIdentityContext();
+    if (protection === 'auth' && identityContext?.isOnboarded === false) {
+      return { location: '/setup' };
+    }
+
+    return null;
+  },
+});
+```
+
+Use this for framework/app coordination, not domain constants.
+
+## Permission Route Protection
+
+Use `configurePermissionRouteProtection` to tell Spine how to get the current session and permission context.
+
+```ts
+import { configurePermissionRouteProtection } from '@eminuckan/spine/server';
+
+configurePermissionRouteProtection({
+  getSession: async (request) => {
+    return {
+      user: { sub: '123' },
+      accessToken: 'token',
+    };
+  },
+  resolveContext: async () => {
+    return {
+      permissions: ['Identity.Users.View'],
+      currentTenant: 'tenant-1',
+    };
+  },
+});
+```
+
+## API Client Adaptation
+
+Use `createAPIConfigFactory` to keep auth and tenant resolution centralized.
+
+```ts
+import { createAPIConfigFactory } from '@eminuckan/spine/api-client/server';
+
+const { createAPIConfig, getAPIBaseURL } = createAPIConfigFactory(
+  getAccessToken,
+  getCurrentTenant,
+  logger,
+  {
+    baseURL: process.env.API_BASE_URL,
+    userAgent: 'MyApp/1.0',
+    tenantHeaderName: 'X-Workspace-Id',
+  }
+);
+```
+
+If your backend does not use bearer auth or tenant headers, set `authHeaderName`
+or `tenantHeaderName` to `null` and provide `buildHeaders`.
+
+## Practical Rule
+
+If the value could change from one backend to another, it should usually be configured.
+
+Examples:
+
+- claim names
+- endpoint paths and response shapes
+- logout URLs
+- cookie policies
+- redirect decisions
+- auth and tenant header names
+- permission loading
+
+If the logic is universal infrastructure, it should usually stay in core.

package/docs/codex-for-oss-application.md

@@ -0,0 +1,31 @@
+# Codex For Open Source Application Notes
+
+This is the maintainer-facing application packet for the Codex for Open Source program. Do not add secrets, private customer details, or non-public product information here.
+
+## Repository
+
+- GitHub: `https://github.com/eminuckan/spine`
+- npm: `https://www.npmjs.com/package/@eminuckan/spine`
+- Package: `@eminuckan/spine`
+- License: MIT
+- Role: primary maintainer
+
+## Qualification Draft
+
+Spine is an MIT SaaS frontend infrastructure library for auth, identity, tenancy, permissions, API access, realtime clients, and framework adapters. It is extracted from repeated production-facing SaaS frontend needs, has a published npm package, docs, tests, CI, and an example app, and is being maintained as a reusable OSS foundation.
+
+## API Credit Use Draft
+
+Use Codex for core OSS maintenance: PR review, issue triage, release checklist automation, security review of auth/session code, docs drift checks, adapter scaffolding for Next.js/Clerk/Supabase, and regression repair. All changes remain maintainer-reviewed and must pass `pnpm check`.
+
+## Anything Else Draft
+
+Spine is early-stage but solves a common repeated SaaS problem: teams copy auth, tenant, permission, API, query, and realtime infrastructure between apps. The project has been rebooted as independent OSS with generic contracts, public docs, tests, issue templates, roadmap, and a maintenance plan for Codex-assisted review and release work.
+
+## Evidence To Refresh Before Submission
+
+- GitHub stars, forks, issues, pull requests, and latest push date.
+- npm version and last-month download count.
+- CI status on the default branch.
+- Latest published changelog entry.
+- Public production-facing usage links, if the maintainer wants to include them in the private form.

package/docs/codex-maintenance.md

@@ -0,0 +1,47 @@
+# Codex Maintenance Plan
+
+This document explains how Spine intends to use Codex for open source maintenance work.
+
+## Goal
+
+Spine is a compact infrastructure library, but the maintenance surface is broad: auth, identity, tenancy, permissions, API access, realtime clients, framework adapters, examples, tests, docs, and release workflows. Codex should reduce maintainer load while keeping human review and ownership explicit.
+
+## Planned Workflows
+
+- Pull request review: summarize changes, identify risk areas, suggest missing tests, and check public API impact.
+- Issue triage: classify bug reports, adapter requests, backend-contract questions, and documentation gaps.
+- Release workflow: verify changelog entries, package contents, CI status, and npm dry runs before publishing.
+- Documentation maintenance: keep installation, backend adaptation, adapter, and module reference docs aligned with code.
+- Adapter scaffolding: draft Next.js, Clerk, Supabase, Vue, and Svelte adapter experiments behind issues and review gates.
+- Security hardening: review session, OIDC, redirect, cookie, and token-handling changes with focused checklists.
+- Regression repair: investigate failing tests or consuming-app compatibility issues without leaking app-specific policy into core.
+
+## Guardrails
+
+- The maintainer makes final merge and release decisions.
+- All code changes must pass `pnpm check`.
+- Package contents should be checked with `npm pack --dry-run` before publishing.
+- Private application code, credentials, tokens, customer data, and non-public business context should not be included in public issues or documentation.
+- Codex should not scan or review repositories unless the maintainer owns them or has authorization.
+- Product-specific behavior should stay in consuming apps unless it has been generalized and documented.
+
+## API Credit Use
+
+API credits would be used for:
+
+- automated pull request review experiments
+- issue triage and duplicate detection
+- release checklist automation
+- security-focused reviews for auth and session code
+- adapter proof-of-concept generation
+- documentation drift checks between source and public docs
+
+These are core OSS maintenance tasks, not product-specific development work.
+
+## Success Signals
+
+- Faster response time on issues and pull requests.
+- More complete adapter examples without expanding core policy.
+- Fewer release mistakes.
+- Better test coverage for security-sensitive code.
+- Clearer docs for teams integrating Spine into different SaaS backends.