@obsidiane/auth-client-js 1.0.1

package/DEVELOPMENT.md

@@ -0,0 +1,226 @@
+# Development Guide
+
+## Architecture Overview
+
+```
+@obsidiane/auth-client-js
+├── Bridge (Meridiane-generated)      ← Auto-generated from OpenAPI
+│   ├── src/lib/                      ← HTTP client, facades, interceptors
+│   ├── src/models/                   ← TypeScript types
+│   └── src/public-api.ts             ← Main exports
+│
+└── Config
+    ├── package.json                  ← NPM metadata
+    ├── tsconfig.json                 ← TypeScript config
+    └── .gitignore                    ← Ignore generated /src/
+```
+
+## File Structure
+
+### Generated Files (auto-ignored)
+
+```
+src/                           ← GENERATED by Meridiane, ignored in git
+├── lib/
+│   ├── bridge/
+│   │   ├── rest/              ← HTTP adapters
+│   │   └── sse/               ← Realtime (optional)
+│   ├── facades/               ← Resource facades
+│   ├── interceptors/          ← HTTP interceptors
+│   ├── ports/                 ← Interfaces
+│   ├── utils/                 ← Helpers
+│   ├── provide-bridge.ts      ← Angular provider
+│   ├── bridge.types.ts        ← Core types
+│   └── tokens.ts              ← DI tokens
+├── models/                    ← Generated from OpenAPI schemas
+└── public-api.ts              ← Main exports
+```
+
+### Manual Files (version-controlled)
+
+```
+package.json
+tsconfig.json
+README.md
+DEVELOPMENT.md (this file)
+.gitignore
+```
+
+## Regeneration Workflow
+
+### When Backend API Changes
+
+1. **Backend deploys** new endpoints to `/api/docs.json`
+
+2. **Run generation**:
+   ```bash
+   make sdks
+   ```
+
+3. **What happens**:
+   - Downloads OpenAPI spec from `http://localhost:9000/api/docs.json`
+   - Runs Meridiane to generate the bridge
+   - Copies `src/` into `packages/auth-client-js/src/`
+
+4. **Commit**:
+   ```bash
+   git add packages/auth-client-js/
+   git commit -m "chore: regenerate SDKs from OpenAPI spec"
+   ```
+
+5. **Publish** (if needed):
+   ```bash
+   cd packages/auth-client-js
+   npm run build
+   npm publish
+   ```
+
+## Adding New Features
+
+### Scenario 1: New HTTP Endpoint
+
+**The endpoint is added in the backend API** → automatically generated by Meridiane.
+
+```bash
+make sdk-npm
+# Done! New endpoint is in src/ automatically
+```
+
+## Building for Publication
+
+```bash
+# Install dependencies (if needed for TypeScript compilation)
+npm install
+
+# Build TypeScript → JavaScript
+npm run build
+
+# Output in ./dist/
+ls -la dist/
+
+# Publish to npm
+npm publish
+```
+
+## Using in Applications
+
+### In Angular App
+
+```typescript
+// app.config.ts
+import { provideBridge } from '@obsidiane/auth-client-js';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideBridge({
+      baseUrl: 'http://localhost:9000',
+    }),
+  ],
+};
+```
+
+### In a Service
+
+```typescript
+import { FacadeFactory } from '@obsidiane/auth-client-js';
+import type { UserUserRead } from '@obsidiane/auth-client-js';
+
+@Injectable({ providedIn: 'root' })
+export class UsersService {
+  private readonly factory = inject(FacadeFactory);
+  private readonly facade = this.factory.create<UserUserRead>({
+    url: '/api/users',
+  });
+
+  getAll() {
+    return this.facade.getCollection$();
+  }
+
+  getOne(id: string) {
+    return this.facade.get$(id);
+  }
+}
+```
+
+## Testing
+
+The bridge (Meridiane) is tested separately in its own project.
+
+## Troubleshooting
+
+### Build Fails
+
+```bash
+npm run build
+
+# If tsc not found
+npm install
+npm run build
+```
+
+### "Cannot find module 'src/public-api'"
+
+The `src/` folder doesn't exist. You need to generate it:
+
+```bash
+make sdk-npm
+```
+
+## CI/CD Integration
+
+Example GitHub Actions workflow:
+
+```yaml
+name: Publish SDK
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      # Regenerate from OpenAPI (ensures freshness)
+      - run: make sdk-npm
+
+      # Build
+      - run: npm ci
+        working-directory: packages/auth-client-js
+      - run: npm run build
+        working-directory: packages/auth-client-js
+
+      # Publish to npm
+      - run: npm publish
+        working-directory: packages/auth-client-js
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+## Synchronization with webfront/bridge
+
+Both the SDK and the webfront bridge are generated from the same OpenAPI spec:
+
+- **webfront/bridge**: Direct use in the Angular app
+- **packages/auth-client-js**: Packaged for reuse in other projects
+
+They should be **identical in functionality** but:
+- Bridge: used directly via imports (`import { provideBridge }`)
+- SDK: packaged as npm module (`npm install @obsidiane/auth-client-js`)
+
+Both can coexist in your monorepo.
+
+## Maintenance Checklist
+
+- [ ] Run `make sdks` after API changes
+- [ ] Version bump before publishing (in `package.json`)
+- [ ] Run `npm run build` before release
+- [ ] Commit `package.json` + `package-lock.json` changes
+
+## References
+
+- [Meridiane Documentation](https://github.com/obsidiane-lab/meridiane)
+- [Angular HTTP Client](https://angular.io/guide/http)
+- [Angular Dependency Injection](https://angular.io/guide/dependency-injection)

package/README.md

@@ -0,0 +1,181 @@
+# @obsidiane/auth-client-js
+
+Obsidiane Auth API Client for Angular/TypeScript.
+
+A lightweight SDK for interacting with the Obsidiane Auth service, featuring:
+- **Bridge from Meridiane**: Auto-generated HTTP client, facades, and TypeScript models from OpenAPI spec
+- **Zero runtime dependencies**: Uses native browser APIs and Angular's built-in HTTP client
+
+## Installation
+
+```bash
+npm install @obsidiane/auth-client-js
+```
+
+## Quick Start
+
+### 1. Setup in your Angular app
+
+```typescript
+// app.config.ts
+import { provideBridge } from '@obsidiane/auth-client-js';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    // Provide the Meridiane bridge (HTTP client + facades)
+    provideBridge({
+      baseUrl: 'http://localhost:9000',
+    }),
+
+  ],
+};
+```
+
+### 2. Use in your services
+
+```typescript
+import { Injectable, inject } from '@angular/core';
+import { FacadeFactory } from '@obsidiane/auth-client-js';
+import type { UserUserRead } from '@obsidiane/auth-client-js';
+
+@Injectable({ providedIn: 'root' })
+export class AuthService {
+  private readonly factory = inject(FacadeFactory);
+  private readonly users = this.factory.create<UserUserRead>({
+    url: '/api/users',
+  });
+
+  getUsers() {
+    return this.users.getCollection$();
+  }
+
+  getUser(id: string) {
+    return this.users.get$(id);
+  }
+}
+```
+
+## API Reference
+
+### Bridge Exports (from Meridiane)
+
+The bridge provides:
+
+#### **FacadeFactory**
+Create resource facades for CRUD operations:
+
+```typescript
+const facade = factory.create<MyResource>({
+  url: '/api/resources',
+});
+
+// Collection operations
+facade.getCollection$({ page: 1, itemsPerPage: 20 })
+
+// Item operations
+facade.get$(id)
+facade.post$(item)
+facade.patch$(id, partialItem)
+facade.delete$(id)
+```
+
+#### **BridgeFacade**
+Low-level HTTP client for custom endpoints:
+
+```typescript
+const bridge = inject(BridgeFacade);
+
+// Custom GET
+bridge.get$<MyResponse>('/api/custom-endpoint')
+
+// Custom POST
+bridge.post$<MyResponse>('/api/custom-endpoint', { payload })
+```
+
+#### **Models**
+TypeScript types for all API resources:
+
+```typescript
+import type {
+  UserUserRead,
+  Auth,
+  InviteUserInviteRead,
+  // ... all other models
+} from '@obsidiane/auth-client-js';
+```
+
+## How It Works
+
+### Bridge Layer (Meridiane)
+
+The bridge is auto-generated from the OpenAPI spec (`/api/docs.json`) using Meridiane. It includes:
+
+- **HTTP Client**: Optimized fetch wrapper with automatic retries and deduplication
+- **Facades**: Resource-based API for common CRUD operations
+- **Models**: TypeScript interfaces for all API request/response types
+- **Interceptors**: Built-in handling for headers, errors, and single-flight requests
+
+## Development
+
+### Regenerate from OpenAPI
+
+The bridge is regenerated from the backend OpenAPI spec:
+
+```bash
+# From project root
+make sdk-npm
+
+# Or manually
+npx meridiane generate "@obsidiane/auth-client-js" \
+  --spec http://localhost:9000/api/docs.json \
+  --formats "application/ld+json"
+```
+
+### Build
+
+```bash
+npm run build
+# Output: ./dist/
+```
+
+### Publish
+
+```bash
+npm publish
+```
+
+## Migration from Old SDK
+
+The old SDK (`packages/auth-client-js.backup/`) had 758 lines of custom HTTP client code. This new version:
+
+- **Removes**: Custom HTTP client, request builders, response decoders
+- **Adds**: Meridiane bridge for consistency with the main app
+
+The API remains similar but cleaner:
+
+```typescript
+// Old way (custom client)
+import { AuthClient } from '@obsidiane/auth-client-js';
+const client = new AuthClient({ baseUrl: 'http://localhost:9000' });
+client.auth.login(email, password);
+
+// New way (Meridiane bridge)
+import { BridgeFacade } from '@obsidiane/auth-client-js';
+const bridge = inject(BridgeFacade);
+bridge.post$('/api/auth/login', { email, password });
+```
+
+## Architecture
+
+```
+@obsidiane/auth-client-js
+├── Bridge (Meridiane-generated)
+│   ├── HTTP client (fetch wrapper)
+│   ├── Facades (FacadeFactory, BridgeFacade)
+│   ├── Models (TypeScript interfaces)
+│   └── Interceptors
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * Obsidiane Auth Client for Angular/TypeScript
+ *
+ * Main entry point that exports the Meridiane-generated bridge:
+ * - HTTP client (BridgeFacade)
+ * - Facades (resource-based API)
+ * - Models (auto-generated types from OpenAPI)
+ */
+export * from './src/public-api';
+//# sourceMappingURL=index.js.map

package/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Obsidiane Auth Client for Angular/TypeScript
+ *
+ * Main entry point that exports the Meridiane-generated bridge:
+ * - HTTP client (BridgeFacade)
+ * - Facades (resource-based API)
+ * - Models (auto-generated types from OpenAPI)
+ */
+
+export * from './src/public-api';

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@obsidiane/auth-client-js",
+  "version": "1.0.1",
+  "description": "Obsidiane Auth API Client - Angular/TypeScript SDK",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublish": "npm run build"
+  },
+  "peerDependencies": {
+    "@angular/common": "^20.0.0",
+    "@angular/core": "^20.0.0",
+    "rxjs": "^7.8.0"
+  },
+  "dependencies": {
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@angular/common": "^20.0.2",
+    "@angular/core": "^20.0.2",
+    "rxjs": "^7.8.1",
+    "typescript": "^5.8.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/obsidiane-lab/obsidiane-auth.git",
+    "directory": "packages/auth-client-js"
+  },
+  "license": "MIT",
+  "keywords": [
+    "auth",
+    "authentication",
+    "obsidiane",
+    "api-client",
+    "angular"
+  ]
+}

package/src/lib/bridge/rest/api-platform.adapter.ts

@@ -0,0 +1,84 @@
+import {HttpClient} from '@angular/common/http';
+import {Observable} from 'rxjs';
+import {toHttpParams} from './query-builder';
+import {buildHttpRequestOptions} from './http-request.options';
+import {
+  Collection,
+  HttpCallOptions,
+  HttpRequestConfig,
+  Iri,
+  IriRequired,
+  Item,
+  AnyQuery,
+  ResourceRepository,
+} from '../../ports/resource-repository.port';
+import {resolveUrl} from '../../utils/url';
+
+export class ApiPlatformRestRepository<T extends Item> implements ResourceRepository<T> {
+  constructor(
+    private readonly http: HttpClient,
+    private readonly apiBase: string,
+    private readonly resourcePath: Iri,
+    private readonly withCredentialsDefault: boolean,
+  ) {
+  }
+
+  getCollection$(query?: AnyQuery, opts?: HttpCallOptions): Observable<Collection<T>> {
+    const params = toHttpParams(query);
+    return this.http.get<Collection<T>>(this.resolveUrl(this.resourcePath), {
+      params,
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
+    });
+  }
+
+  get$(iri: IriRequired, opts?: HttpCallOptions): Observable<T> {
+    return this.http.get<T>(this.resolveUrl(iri), {
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
+    });
+  }
+
+  post$(payload: Partial<T>, opts?: HttpCallOptions): Observable<T> {
+    return this.http.post<T>(this.resolveUrl(this.resourcePath), payload, {
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
+    });
+  }
+
+  patch$(iri: IriRequired, changes: Partial<T>, opts?: HttpCallOptions): Observable<T> {
+    return this.http.patch<T>(this.resolveUrl(iri), changes, {
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
+    });
+  }
+
+  put$(iri: IriRequired, payload: Partial<T>, opts?: HttpCallOptions): Observable<T> {
+    return this.http.put<T>(this.resolveUrl(iri), payload, {
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
+    });
+  }
+
+  delete$(iri: IriRequired, opts?: HttpCallOptions): Observable<void> {
+    return this.http.delete<void>(this.resolveUrl(iri), {
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
+    });
+  }
+
+  request$<R = unknown, B = unknown>(req: HttpRequestConfig<B>): Observable<R> {
+    // Low-level escape hatch for non-standard endpoints (custom controllers, uploads, etc.).
+    const {method, url} = req;
+
+    const targetUrl = this.resolveUrl(url ?? this.resourcePath);
+    const mergedOptions = buildHttpRequestOptions(req, {withCredentialsDefault: this.withCredentialsDefault});
+    return this.http.request<R>(method, targetUrl, mergedOptions as {observe: 'body'});
+  }
+
+  private resolveUrl(path?: Iri): string {
+    const effectivePath = path ?? this.resourcePath;
+    if (!effectivePath) throw new Error('ApiPlatformRestRepository: missing url and resourcePath');
+    return resolveUrl(this.apiBase, effectivePath);
+  }
+}

package/src/lib/bridge/rest/http-request.options.ts

@@ -0,0 +1,21 @@
+import {HttpRequestConfig} from '../../ports/resource-repository.port';
+import {toHttpParams} from './query-builder';
+
+export function buildHttpRequestOptions(
+  req: HttpRequestConfig,
+  {withCredentialsDefault}: {withCredentialsDefault: boolean}
+): Record<string, unknown> {
+  const {query, body, headers, responseType, withCredentials, options = {}} = req;
+  const mergedOptions: Record<string, unknown> = {...options};
+
+  if (headers) mergedOptions['headers'] = headers;
+  if (query) mergedOptions['params'] = toHttpParams(query);
+  if (body !== undefined) mergedOptions['body'] = body;
+
+  mergedOptions['responseType'] = (responseType ?? (mergedOptions['responseType'] as any) ?? 'json') as any;
+  mergedOptions['withCredentials'] =
+    withCredentials ?? (mergedOptions['withCredentials'] as any) ?? withCredentialsDefault;
+  mergedOptions['observe'] = 'body';
+
+  return mergedOptions;
+}

package/src/lib/bridge/rest/query-builder.ts

@@ -0,0 +1,43 @@
+import {HttpParams} from '@angular/common/http';
+import {AnyQuery, Query, QueryParamValue} from '../../ports/resource-repository.port';
+
+export function toHttpParams(q: AnyQuery | undefined): HttpParams {
+  if (!q) return new HttpParams();
+  if (q instanceof HttpParams) return q;
+
+  const fromObject: Record<string, string | string[]> = {};
+
+  const consumed = new Set<string>();
+  const maybeQuery = q as Query;
+  if (maybeQuery.page != null) {
+    fromObject['page'] = String(maybeQuery.page);
+    consumed.add('page');
+  }
+  if (maybeQuery.itemsPerPage != null) {
+    fromObject['itemsPerPage'] = String(maybeQuery.itemsPerPage);
+    consumed.add('itemsPerPage');
+  }
+
+  if (q.filters) {
+    consumed.add('filters');
+    for (const [k, v] of Object.entries(q.filters)) {
+      assign(fromObject, k, v);
+    }
+  }
+
+  for (const [k, v] of Object.entries(q as Record<string, QueryParamValue>)) {
+    if (consumed.has(k)) continue;
+    assign(fromObject, k, v);
+  }
+
+  return new HttpParams({fromObject});
+}
+
+function assign(target: Record<string, string | string[]>, key: string, value: QueryParamValue | undefined) {
+  if (value == null) return;
+  if (Array.isArray(value)) {
+    target[key] = value.map(String);
+  } else {
+    target[key] = String(value);
+  }
+}

package/src/lib/bridge/sse/eventsource-wrapper.ts

@@ -0,0 +1,70 @@
+import {ReplaySubject, Subject} from 'rxjs';
+import {SseEvent, SseOptions, RealtimeStatus} from '../../ports/realtime.port';
+import {BridgeLogger} from '../../bridge.types';
+
+export class EventSourceWrapper {
+  private es?: EventSource;
+
+  private readonly statusSub = new ReplaySubject<RealtimeStatus>(1);
+  private readonly eventSub = new Subject<SseEvent>();
+
+  readonly status$ = this.statusSub.asObservable();
+  readonly events$ = this.eventSub.asObservable();
+
+  constructor(
+    private readonly url: string,
+    private readonly opts: SseOptions = {},
+    private readonly logger?: BridgeLogger,
+  ) {
+    this.setState('closed');
+    this.log('[SSE] init', {url, withCredentials: !!opts.withCredentials});
+  }
+
+  open(): void {
+    if (this.es) {
+      this.log('[SSE] open() ignored: already open');
+      return;
+    }
+
+    this.setState('connecting');
+    this.log('[SSE] open', {url: this.url});
+
+    const es = new EventSource(this.url, {
+      withCredentials: !!this.opts.withCredentials,
+    });
+    this.es = es;
+
+    es.onopen = () => {
+      this.setState('connected');
+    };
+
+    es.onmessage = (ev) => {
+      this.eventSub.next({type: 'message', data: ev.data, lastEventId: ev.lastEventId || undefined});
+    };
+
+    es.onerror = () => {
+      // The browser will retry automatically. We stay in "connecting".
+      this.log('[SSE] error');
+      this.setState('connecting');
+    };
+  }
+
+  close(): void {
+    if (this.es) {
+      this.es.close();
+      this.es = undefined;
+      this.log('[SSE] closed');
+    }
+    this.setState('closed');
+  }
+
+  // ──────────────── internals ────────────────
+
+  private setState(state: RealtimeStatus): void {
+    this.statusSub.next(state);
+  }
+
+  private log(...args: unknown[]): void {
+    this.logger?.debug?.(...args);
+  }
+}