@forjacms/client 1.2.6

package/README.md

@@ -0,0 +1,282 @@
+# @forjacms/client
+
+Typed TypeScript SDK for the Forja CMS content API. Works in Node.js, browsers, and edge runtimes.
+
+## Install
+
+```bash
+npm install @forjacms/client
+```
+
+## Quick Start
+
+```typescript
+import { ForjaClient } from '@forjacms/client';
+
+const forja = new ForjaClient({
+  baseUrl: 'https://cms.example.com/api/v1',
+  apiKey: 'dk_read_...',
+  siteId: 'your-site-uuid',
+});
+```
+
+## Usage
+
+### Blogs
+
+```typescript
+// Published blogs (paginated)
+const blogs = await forja.blogs.listPublished({ page: 1, pageSize: 10 });
+console.log(blogs.data);    // BlogListItem[]
+console.log(blogs.meta);    // { page, page_size, total_pages, total_items }
+
+// By category
+const techBlogs = await forja.blogs.listByCategory('tech', { page: 1 });
+
+// Featured blogs
+const featured = await forja.blogs.listFeatured({ limit: 5 });
+
+// Similar posts
+const similar = await forja.blogs.listSimilar('blog-uuid', { limit: 3 });
+
+// Single blog (returns null if not found)
+const blog = await forja.blogs.get('my-blog-slug');
+
+// RSS feed
+const rss = await forja.blogs.rss();
+```
+
+### Pages
+
+```typescript
+// Get page by route (returns null if not found)
+const page = await forja.pages.getByRoute('/about');
+
+// Page sections
+const sections = await forja.pages.getSections('page-uuid');
+
+// Section translations
+const translations = await forja.pages.getSectionLocalizations('section-uuid');
+```
+
+### Navigation
+
+```typescript
+// All menus
+const menus = await forja.navigation.listMenus();
+
+// Single menu by slug
+const primary = await forja.navigation.getMenuBySlug('primary');
+
+// Navigation tree (with optional locale)
+const tree = await forja.navigation.getTree('menu-uuid', { locale: 'de' });
+
+// Menu items
+const items = await forja.navigation.listItems('menu-uuid');
+```
+
+### Taxonomy
+
+```typescript
+// Tags (paginated, searchable)
+const tags = await forja.taxonomy.listTags({ search: 'rust', sortBy: 'slug' });
+
+// Categories
+const categories = await forja.taxonomy.listCategories();
+
+// Categories with blog counts
+const withCounts = await forja.taxonomy.getCategoriesWithBlogCounts();
+
+// Tags/categories for a specific content item
+const contentTags = await forja.taxonomy.getContentTags('content-uuid');
+```
+
+### Analytics
+
+```typescript
+// Track a pageview
+await forja.analytics.trackPageview({ path: '/blog/hello-world' });
+
+// Analytics report
+const report = await forja.analytics.getReport({ days: 30, topN: 10 });
+console.log(report.total_views, report.total_unique_visitors);
+
+// Page-specific analytics
+const pageStats = await forja.analytics.getPageAnalytics({
+  path: '/blog/hello-world',
+  days: 7,
+});
+```
+
+### CV / Resume
+
+```typescript
+// Skills
+const skills = await forja.cv.listSkills({ page: 1 });
+const skill = await forja.cv.getSkillBySlug('typescript');
+
+// CV entries filtered by type
+const workHistory = await forja.cv.listEntries({ entryType: 'Work' });
+```
+
+### Legal
+
+```typescript
+// Legal documents
+const docs = await forja.legal.list();
+const privacy = await forja.legal.getBySlug('privacy-policy');
+
+// Cookie consent
+const consent = await forja.legal.getCookieConsent();
+```
+
+## Pagination
+
+All paginated responses include helpers for navigating pages:
+
+```typescript
+const page1 = await forja.blogs.listPublished({ pageSize: 10 });
+
+// Fetch next page
+const page2 = await page1.fetchNext(); // null if on last page
+
+// Fetch all items across all pages
+const allBlogs = await page1.fetchAll();
+
+// Async iterator
+for await (const page of page1) {
+  console.log(page.data);
+}
+```
+
+## Error Handling
+
+The SDK throws typed errors for different failure scenarios:
+
+```typescript
+import {
+  ForjaAuthError,
+  ForjaPermissionError,
+  ForjaRateLimitError,
+  ForjaValidationError,
+  ForjaServerError,
+  ForjaNetworkError,
+} from '@forjacms/client';
+
+try {
+  const blogs = await forja.blogs.listPublished();
+} catch (error) {
+  if (error instanceof ForjaAuthError) {
+    // Invalid or missing API key (401)
+  } else if (error instanceof ForjaRateLimitError) {
+    // Rate limited (429) — check error.retryAfter
+    console.log(`Retry after ${error.retryAfter} seconds`);
+  } else if (error instanceof ForjaNetworkError) {
+    // Network failure — server unreachable
+  }
+}
+```
+
+Methods that fetch a single resource by ID or slug return `null` instead of throwing on 404.
+
+## Custom Fetch
+
+Pass a custom `fetch` implementation for edge runtimes or testing:
+
+```typescript
+const forja = new ForjaClient({
+  baseUrl: 'https://cms.example.com/api/v1',
+  apiKey: 'dk_read_...',
+  siteId: 'your-site-uuid',
+  fetch: customFetchFn,
+});
+```
+
+## Framework Integration
+
+### React
+
+```typescript
+import { ForjaClient } from '@forjacms/client';
+import { useEffect, useState } from 'react';
+
+const forja = new ForjaClient({ baseUrl: '...', apiKey: '...', siteId: '...' });
+
+function BlogList() {
+  const [blogs, setBlogs] = useState([]);
+
+  useEffect(() => {
+    forja.blogs.listPublished({ page: 1 }).then((res) => setBlogs(res.data));
+  }, []);
+
+  return blogs.map((b) => <article key={b.id}>{b.slug}</article>);
+}
+```
+
+### Angular (v17+)
+
+The `@forjacms/client/angular` subpath provides Angular DI integration and a signal-based resource helper.
+
+**Setup:**
+
+```typescript
+// app.config.ts
+import { provideForja } from '@forjacms/client/angular';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideForja({
+      baseUrl: environment.cmsApiUrl,
+      apiKey: environment.cmsApiKey,
+      siteId: environment.cmsSiteId,
+    }),
+  ],
+};
+```
+
+**Usage in components:**
+
+```typescript
+import { Component } from '@angular/core';
+import { injectForja, forjaResource } from '@forjacms/client/angular';
+
+@Component({
+  template: `
+    @if (blogs.isLoading()) {
+      <p>Loading...</p>
+    } @else if (blogs.error()) {
+      <p>Error: {{ blogs.error()!.message }}</p>
+    } @else {
+      @for (blog of blogs.value()!.data; track blog.id) {
+        <article>{{ blog.slug }}</article>
+      }
+    }
+    <button (click)="blogs.reload()">Refresh</button>
+  `,
+})
+export class BlogListComponent {
+  private forja = injectForja();
+  blogs = forjaResource(() => this.forja.blogs.listPublished({ page: 1 }));
+}
+```
+
+The `forjaResource()` helper returns an object with:
+- `value()` — Signal with the resolved data (or `undefined` while loading)
+- `isLoading()` — Signal indicating loading state
+- `error()` — Signal with the error (or `null` on success)
+- `reload()` — Re-execute the loader
+
+### Vanilla TypeScript
+
+```typescript
+import { ForjaClient } from '@forjacms/client';
+
+const forja = new ForjaClient({ baseUrl: '...', apiKey: '...', siteId: '...' });
+
+const blogs = await forja.blogs.listPublished();
+document.getElementById('count')!.textContent = `${blogs.meta.total_items} posts`;
+```
+
+## License
+
+AGPL-3.0-or-later

package/dist/angular/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`../client-eFMh_n88.cjs`);let t=require(`@angular/core`);const n=new t.InjectionToken(`ForjaClient`);function r(r){return(0,t.makeEnvironmentProviders)([{provide:n,useFactory:()=>new e.t(r)}])}function i(){return(0,t.inject)(n)}function a(e){let n=(0,t.signal)(void 0),r=(0,t.signal)(!0),i=(0,t.signal)(null),a=()=>{r.set(!0),i.set(null),e().then(e=>n.set(e)).catch(e=>i.set(e instanceof Error?e:Error(String(e)))).finally(()=>r.set(!1))};return a(),{value:n.asReadonly(),isLoading:r.asReadonly(),error:i.asReadonly(),reload:a}}exports.FORJA_CLIENT=n,exports.forjaResource=a,exports.injectForja=i,exports.provideForja=r;

package/dist/angular/index.d.cts

@@ -0,0 +1,140 @@
+import { b as ForjaClientConfig, t as ForjaClient } from "../client-BBAKLM2r.cjs";
+import { EnvironmentProviders, InjectionToken, Signal } from "@angular/core";
+
+//#region src/angular/provider.d.ts
+/**
+ * Angular injection token for the {@link ForjaClient} instance.
+ *
+ * You don't need to use this directly — use {@link provideForja} and
+ * {@link injectForja} instead.
+ */
+declare const FORJA_CLIENT: InjectionToken<ForjaClient>;
+/**
+ * Provide the Forja SDK client to Angular's dependency injection system.
+ *
+ * Call this in your application's `providers` array (typically in `app.config.ts`)
+ * to make the {@link ForjaClient} available via {@link injectForja}.
+ *
+ * @param config - API connection settings.
+ * @param config.baseUrl - Full URL to the Forja API (e.g. `https://cms.example.com/api/v1`).
+ * @param config.apiKey - API key with at least `Read` permission.
+ * @param config.siteId - UUID of the site to query.
+ * @returns Angular environment providers to include in your app config.
+ *
+ * @example
+ * ```typescript
+ * // app.config.ts
+ * import { provideForja } from '@forjacms/client/angular';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideForja({
+ *       baseUrl: environment.cmsApiUrl,
+ *       apiKey: environment.cmsApiKey,
+ *       siteId: environment.cmsSiteId,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+declare function provideForja(config: ForjaClientConfig): EnvironmentProviders;
+/**
+ * Inject the {@link ForjaClient} instance from Angular's DI system.
+ *
+ * Must be called in an injection context (component constructor, `inject()` call,
+ * or factory function). Requires {@link provideForja} to be configured in the
+ * application's providers.
+ *
+ * @returns The configured {@link ForjaClient} instance.
+ * @throws If called outside an injection context or without {@link provideForja}.
+ *
+ * @example
+ * ```typescript
+ * import { Component } from '@angular/core';
+ * import { injectForja, forjaResource } from '@forjacms/client/angular';
+ *
+ * @Component({
+ *   template: `
+ *     @if (blogs.isLoading()) { <p>Loading...</p> }
+ *     @for (blog of blogs.value()?.data ?? []; track blog.id) {
+ *       <p>{{ blog.slug }}</p>
+ *     }
+ *   `,
+ * })
+ * export class BlogListComponent {
+ *   private forja = injectForja();
+ *   blogs = forjaResource(() => this.forja.blogs.listPublished({ page: 1 }));
+ * }
+ * ```
+ */
+declare function injectForja(): ForjaClient;
+//#endregion
+//#region src/angular/resource.d.ts
+/**
+ * A reactive resource that wraps an async operation with Angular signals.
+ *
+ * Provides `value`, `isLoading`, and `error` signals for template binding,
+ * plus a `reload()` method to re-execute the loader.
+ *
+ * @typeParam T - The type of the resolved value.
+ */
+interface ForjaResource<T> {
+  /** The resolved value, or `undefined` while loading or after an error. */
+  readonly value: Signal<T | undefined>;
+  /** `true` while the loader is executing. */
+  readonly isLoading: Signal<boolean>;
+  /** The error if the loader rejected, or `null` on success. */
+  readonly error: Signal<Error | null>;
+  /** Re-execute the loader, resetting `isLoading` and clearing `error`. */
+  readonly reload: () => void;
+}
+/**
+ * Create a signal-based resource from an async loader function.
+ *
+ * Immediately invokes the loader and exposes the result via Angular signals.
+ * Use in Angular components to bind async SDK calls to templates without
+ * manual subscribe/unsubscribe boilerplate.
+ *
+ * @typeParam T - The type returned by the loader promise.
+ * @param loader - A function that returns a `Promise<T>`. Called immediately and on each `reload()`.
+ * @returns A {@link ForjaResource} with reactive `value`, `isLoading`, and `error` signals.
+ *
+ * @example
+ * ```typescript
+ * import { Component } from '@angular/core';
+ * import { injectForja, forjaResource } from '@forjacms/client/angular';
+ *
+ * @Component({
+ *   template: `
+ *     @if (blogs.isLoading()) {
+ *       <p>Loading...</p>
+ *     } @else if (blogs.error()) {
+ *       <p>Error: {{ blogs.error()!.message }}</p>
+ *     } @else {
+ *       @for (blog of blogs.value()!.data; track blog.id) {
+ *         <article>{{ blog.slug }}</article>
+ *       }
+ *     }
+ *     <button (click)="blogs.reload()">Refresh</button>
+ *   `,
+ * })
+ * export class BlogListComponent {
+ *   private forja = injectForja();
+ *   blogs = forjaResource(() => this.forja.blogs.listPublished({ page: 1 }));
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Fetch a single resource
+ * const blog = forjaResource(() => forja.blogs.getBySlug('my-post'));
+ *
+ * // Access in template
+ * // blog.value()?.localizations[0]?.title
+ * // blog.isLoading()
+ * // blog.error()?.message
+ * ```
+ */
+declare function forjaResource<T>(loader: () => Promise<T>): ForjaResource<T>;
+//#endregion
+export { FORJA_CLIENT, type ForjaResource, forjaResource, injectForja, provideForja };

package/dist/angular/index.d.mts

@@ -0,0 +1,140 @@
+import { b as ForjaClientConfig, t as ForjaClient } from "../client-d-QwwKUW.mjs";
+import { EnvironmentProviders, InjectionToken, Signal } from "@angular/core";
+
+//#region src/angular/provider.d.ts
+/**
+ * Angular injection token for the {@link ForjaClient} instance.
+ *
+ * You don't need to use this directly — use {@link provideForja} and
+ * {@link injectForja} instead.
+ */
+declare const FORJA_CLIENT: InjectionToken<ForjaClient>;
+/**
+ * Provide the Forja SDK client to Angular's dependency injection system.
+ *
+ * Call this in your application's `providers` array (typically in `app.config.ts`)
+ * to make the {@link ForjaClient} available via {@link injectForja}.
+ *
+ * @param config - API connection settings.
+ * @param config.baseUrl - Full URL to the Forja API (e.g. `https://cms.example.com/api/v1`).
+ * @param config.apiKey - API key with at least `Read` permission.
+ * @param config.siteId - UUID of the site to query.
+ * @returns Angular environment providers to include in your app config.
+ *
+ * @example
+ * ```typescript
+ * // app.config.ts
+ * import { provideForja } from '@forjacms/client/angular';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideForja({
+ *       baseUrl: environment.cmsApiUrl,
+ *       apiKey: environment.cmsApiKey,
+ *       siteId: environment.cmsSiteId,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+declare function provideForja(config: ForjaClientConfig): EnvironmentProviders;
+/**
+ * Inject the {@link ForjaClient} instance from Angular's DI system.
+ *
+ * Must be called in an injection context (component constructor, `inject()` call,
+ * or factory function). Requires {@link provideForja} to be configured in the
+ * application's providers.
+ *
+ * @returns The configured {@link ForjaClient} instance.
+ * @throws If called outside an injection context or without {@link provideForja}.
+ *
+ * @example
+ * ```typescript
+ * import { Component } from '@angular/core';
+ * import { injectForja, forjaResource } from '@forjacms/client/angular';
+ *
+ * @Component({
+ *   template: `
+ *     @if (blogs.isLoading()) { <p>Loading...</p> }
+ *     @for (blog of blogs.value()?.data ?? []; track blog.id) {
+ *       <p>{{ blog.slug }}</p>
+ *     }
+ *   `,
+ * })
+ * export class BlogListComponent {
+ *   private forja = injectForja();
+ *   blogs = forjaResource(() => this.forja.blogs.listPublished({ page: 1 }));
+ * }
+ * ```
+ */
+declare function injectForja(): ForjaClient;
+//#endregion
+//#region src/angular/resource.d.ts
+/**
+ * A reactive resource that wraps an async operation with Angular signals.
+ *
+ * Provides `value`, `isLoading`, and `error` signals for template binding,
+ * plus a `reload()` method to re-execute the loader.
+ *
+ * @typeParam T - The type of the resolved value.
+ */
+interface ForjaResource<T> {
+  /** The resolved value, or `undefined` while loading or after an error. */
+  readonly value: Signal<T | undefined>;
+  /** `true` while the loader is executing. */
+  readonly isLoading: Signal<boolean>;
+  /** The error if the loader rejected, or `null` on success. */
+  readonly error: Signal<Error | null>;
+  /** Re-execute the loader, resetting `isLoading` and clearing `error`. */
+  readonly reload: () => void;
+}
+/**
+ * Create a signal-based resource from an async loader function.
+ *
+ * Immediately invokes the loader and exposes the result via Angular signals.
+ * Use in Angular components to bind async SDK calls to templates without
+ * manual subscribe/unsubscribe boilerplate.
+ *
+ * @typeParam T - The type returned by the loader promise.
+ * @param loader - A function that returns a `Promise<T>`. Called immediately and on each `reload()`.
+ * @returns A {@link ForjaResource} with reactive `value`, `isLoading`, and `error` signals.
+ *
+ * @example
+ * ```typescript
+ * import { Component } from '@angular/core';
+ * import { injectForja, forjaResource } from '@forjacms/client/angular';
+ *
+ * @Component({
+ *   template: `
+ *     @if (blogs.isLoading()) {
+ *       <p>Loading...</p>
+ *     } @else if (blogs.error()) {
+ *       <p>Error: {{ blogs.error()!.message }}</p>
+ *     } @else {
+ *       @for (blog of blogs.value()!.data; track blog.id) {
+ *         <article>{{ blog.slug }}</article>
+ *       }
+ *     }
+ *     <button (click)="blogs.reload()">Refresh</button>
+ *   `,
+ * })
+ * export class BlogListComponent {
+ *   private forja = injectForja();
+ *   blogs = forjaResource(() => this.forja.blogs.listPublished({ page: 1 }));
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Fetch a single resource
+ * const blog = forjaResource(() => forja.blogs.getBySlug('my-post'));
+ *
+ * // Access in template
+ * // blog.value()?.localizations[0]?.title
+ * // blog.isLoading()
+ * // blog.error()?.message
+ * ```
+ */
+declare function forjaResource<T>(loader: () => Promise<T>): ForjaResource<T>;
+//#endregion
+export { FORJA_CLIENT, type ForjaResource, forjaResource, injectForja, provideForja };

package/dist/angular/index.mjs

@@ -0,0 +1 @@
+import{t as e}from"../client-DTfhjUoX.mjs";import{InjectionToken as t,inject as n,makeEnvironmentProviders as r,signal as i}from"@angular/core";const a=new t(`ForjaClient`);function o(t){return r([{provide:a,useFactory:()=>new e(t)}])}function s(){return n(a)}function c(e){let t=i(void 0),n=i(!0),r=i(null),a=()=>{n.set(!0),r.set(null),e().then(e=>t.set(e)).catch(e=>r.set(e instanceof Error?e:Error(String(e)))).finally(()=>n.set(!1))};return a(),{value:t.asReadonly(),isLoading:n.asReadonly(),error:r.asReadonly(),reload:a}}export{a as FORJA_CLIENT,c as forjaResource,s as injectForja,o as provideForja};