@onagentic/master-data 1.0.0

package/README.md

@@ -0,0 +1,81 @@
+# @onagentic/master-data
+
+Lightweight TypeScript client for fetching master data from a Strapi-compatible REST API.
+
+Supports token auth, pagination, field selection, group filtering, and runtime config updates.
+
+## Install
+
+```bash
+npm install @onagentic/master-data
+```
+
+## Quick start
+
+```ts
+import { createClient } from '@onagentic/master-data';
+
+const client = createClient({
+  baseUrl: 'https://api.example.com',
+  token: process.env.API_TOKEN!,
+});
+
+// Single page (default: page 1, pageSize 100, active only)
+const items = await client.getItems('MASTER_ECO_SERVICES');
+
+// All pages automatically
+const all = await client.fetchAll('MASTER_ECO_SERVICES');
+
+// Full response with pagination meta
+const response = await client.fetch('MASTER_ECO_SERVICES', {
+  pagination: { page: 2, pageSize: 50 },
+  sort: { field: 'label', order: 'asc' },
+  fields: ['documentId', 'key', 'label'],
+  activeOnly: false,
+});
+console.log(response.meta.pagination); // { page, pageSize, pageCount, total }
+```
+
+## Config options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `baseUrl` | `string` | **required** | API base URL |
+| `token` | `string` | **required** | Bearer token |
+| `apiPath` | `string` | `/api/master-datas` | API endpoint path |
+| `defaultFields` | `string[]` | `['documentId','key','label','order','is_active']` | Fields to request |
+| `defaultPageSize` | `number` | `100` | Items per page |
+| `defaultSortField` | `string` | `'order'` | Field to sort by |
+| `defaultSortOrder` | `'asc'\|'desc'` | `'asc'` | Sort direction |
+| `timeout` | `number` | `10000` | Request timeout (ms) |
+
+## Fetch options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `activeOnly` | `boolean` | `true` | Filter `is_active = true` |
+| `fetchAll` | `boolean` | `false` | Auto-paginate all pages (use with `getItems`) |
+| `pagination` | `{ page, pageSize }` | — | Override pagination |
+| `sort` | `{ field, order }` | — | Override sort |
+| `fields` | `string[]` | — | Override fields |
+
+## Runtime config update
+
+```ts
+// e.g. after refreshing a token
+client.updateConfig({ token: 'new-token' });
+```
+
+## Release
+
+```bash
+# bump version
+npm version patch   # or minor / major
+
+# build + test + publish
+npm publish --access public
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1 @@
+'use strict';var m=["documentId","key","label","order","is_active"];var C="order";function D(a){return a.map(([t,e])=>`${encodeURIComponent(t).replace(/%5B/gi,"[").replace(/%5D/gi,"]").replace(/%24/gi,"$")}=${encodeURIComponent(e)}`).join("&")}function h(a,t,e){var d,f,p,g;let r=[],n=((d=t.sort)==null?void 0:d.field)??e.defaultSortField,o=((f=t.sort)==null?void 0:f.order)??e.defaultSortOrder;r.push([`sort[${n}]`,o]);let l=((p=t.pagination)==null?void 0:p.page)??1,i=((g=t.pagination)==null?void 0:g.pageSize)??e.defaultPageSize;r.push(["pagination[page]",String(l)]),r.push(["pagination[pageSize]",String(i)]);let s=t.fields??e.defaultFields;return r.push(["fields",s.join(",")]),r.push(["filters[$and][0][groups][code][$containsi]",a]),t.activeOnly!==false&&r.push(["filters[$and][1][is_active][$eq]","true"]),D(r)}function c(a){return {baseUrl:a.baseUrl.replace(/\/$/,""),token:a.token,apiPath:a.apiPath??"/api/master-datas",defaultFields:a.defaultFields??m,defaultPageSize:a.defaultPageSize??100,defaultSortOrder:a.defaultSortOrder??"asc",defaultSortField:a.defaultSortField??C,timeout:a.timeout??1e4}}var u=class{config;constructor(t){if(!t.baseUrl)throw new Error("[master-data] baseUrl is required");if(!t.token)throw new Error("[master-data] token is required");this.config=c(t);}async fetch(t,e={}){if(!t)throw new Error("[master-data] groupCode is required");let r=h(t,e,this.config),n=`${this.config.baseUrl}${this.config.apiPath}?${r}`,o=new AbortController,l=setTimeout(()=>o.abort(),this.config.timeout),i;try{i=await fetch(n,{method:"GET",headers:{Authorization:`Bearer ${this.config.token}`,"Content-Type":"application/json"},signal:o.signal});}catch(s){throw s.name==="AbortError"?new Error(`[master-data] Request timed out after ${this.config.timeout}ms`):s}finally{clearTimeout(l);}if(!i.ok){let s=await i.text().catch(()=>"");throw new Error(`[master-data] API error ${i.status} ${i.statusText}: ${s}`)}return i.json()}async fetchAll(t,e={}){var l;let r=((l=e.pagination)==null?void 0:l.pageSize)??this.config.defaultPageSize,n=1,o=[];for(;;){let i=await this.fetch(t,{...e,pagination:{page:n,pageSize:r}});o.push(...i.data);let{pageCount:s}=i.meta.pagination;if(n>=s)break;n++;}return o}async getItems(t,e={}){return e.fetchAll?this.fetchAll(t,e):(await this.fetch(t,e)).data}updateConfig(t){let e=c({...this.config,...t});Object.assign(this.config,e);}};function S(a){return new u(a)}exports.MasterDataClient=u;exports.createClient=S;

package/dist/index.d.cts

@@ -0,0 +1,82 @@
+interface MasterDataClientConfig {
+    /** Base URL of the API endpoint (e.g. https://api.example.com) */
+    baseUrl: string;
+    /** Bearer token for authentication */
+    token: string;
+    /** API path prefix (default: /api/master-datas) */
+    apiPath?: string;
+    /** Default fields to fetch (default: documentId,key,label,order,is_active) */
+    defaultFields?: string[];
+    /** Default page size (default: 100) */
+    defaultPageSize?: number;
+    /** Default sort order (default: asc) */
+    defaultSortOrder?: 'asc' | 'desc';
+    /** Default sort field (default: order) */
+    defaultSortField?: string;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+}
+interface PaginationOptions {
+    page?: number;
+    pageSize?: number;
+}
+interface SortOptions {
+    field?: string;
+    order?: 'asc' | 'desc';
+}
+interface FetchOptions {
+    /** Only fetch active items (default: true) */
+    activeOnly?: boolean;
+    pagination?: PaginationOptions;
+    sort?: SortOptions;
+    /** Override default fields */
+    fields?: string[];
+    /** Fetch all pages automatically */
+    fetchAll?: boolean;
+}
+interface MasterDataItem {
+    documentId: string;
+    key: string;
+    label: string;
+    order: number;
+    is_active: boolean;
+    [key: string]: unknown;
+}
+interface PaginationMeta {
+    page: number;
+    pageSize: number;
+    pageCount: number;
+    total: number;
+}
+interface MasterDataResponse {
+    data: MasterDataItem[];
+    meta: {
+        pagination: PaginationMeta;
+    };
+}
+
+declare class MasterDataClient {
+    private readonly config;
+    constructor(config: MasterDataClientConfig);
+    /**
+     * Fetch one page of master data items for the given group code.
+     */
+    fetch(groupCode: string, options?: FetchOptions): Promise<MasterDataResponse>;
+    /**
+     * Fetch ALL pages for the given group code and return a flat item array.
+     * Uses the `fetchAll` flag or call this method directly.
+     */
+    fetchAll(groupCode: string, options?: Omit<FetchOptions, 'fetchAll'>): Promise<MasterDataItem[]>;
+    /**
+     * Convenience: fetch items and return the data array (single page).
+     */
+    getItems(groupCode: string, options?: FetchOptions): Promise<MasterDataItem[]>;
+    /**
+     * Update client config at runtime (e.g. refresh token).
+     */
+    updateConfig(partial: Partial<MasterDataClientConfig>): void;
+}
+
+declare function createClient(config: MasterDataClientConfig): MasterDataClient;
+
+export { type FetchOptions, MasterDataClient, type MasterDataClientConfig, type MasterDataItem, type MasterDataResponse, type PaginationMeta, type PaginationOptions, type SortOptions, createClient };

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+interface MasterDataClientConfig {
+    /** Base URL of the API endpoint (e.g. https://api.example.com) */
+    baseUrl: string;
+    /** Bearer token for authentication */
+    token: string;
+    /** API path prefix (default: /api/master-datas) */
+    apiPath?: string;
+    /** Default fields to fetch (default: documentId,key,label,order,is_active) */
+    defaultFields?: string[];
+    /** Default page size (default: 100) */
+    defaultPageSize?: number;
+    /** Default sort order (default: asc) */
+    defaultSortOrder?: 'asc' | 'desc';
+    /** Default sort field (default: order) */
+    defaultSortField?: string;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+}
+interface PaginationOptions {
+    page?: number;
+    pageSize?: number;
+}
+interface SortOptions {
+    field?: string;
+    order?: 'asc' | 'desc';
+}
+interface FetchOptions {
+    /** Only fetch active items (default: true) */
+    activeOnly?: boolean;
+    pagination?: PaginationOptions;
+    sort?: SortOptions;
+    /** Override default fields */
+    fields?: string[];
+    /** Fetch all pages automatically */
+    fetchAll?: boolean;
+}
+interface MasterDataItem {
+    documentId: string;
+    key: string;
+    label: string;
+    order: number;
+    is_active: boolean;
+    [key: string]: unknown;
+}
+interface PaginationMeta {
+    page: number;
+    pageSize: number;
+    pageCount: number;
+    total: number;
+}
+interface MasterDataResponse {
+    data: MasterDataItem[];
+    meta: {
+        pagination: PaginationMeta;
+    };
+}
+
+declare class MasterDataClient {
+    private readonly config;
+    constructor(config: MasterDataClientConfig);
+    /**
+     * Fetch one page of master data items for the given group code.
+     */
+    fetch(groupCode: string, options?: FetchOptions): Promise<MasterDataResponse>;
+    /**
+     * Fetch ALL pages for the given group code and return a flat item array.
+     * Uses the `fetchAll` flag or call this method directly.
+     */
+    fetchAll(groupCode: string, options?: Omit<FetchOptions, 'fetchAll'>): Promise<MasterDataItem[]>;
+    /**
+     * Convenience: fetch items and return the data array (single page).
+     */
+    getItems(groupCode: string, options?: FetchOptions): Promise<MasterDataItem[]>;
+    /**
+     * Update client config at runtime (e.g. refresh token).
+     */
+    updateConfig(partial: Partial<MasterDataClientConfig>): void;
+}
+
+declare function createClient(config: MasterDataClientConfig): MasterDataClient;
+
+export { type FetchOptions, MasterDataClient, type MasterDataClientConfig, type MasterDataItem, type MasterDataResponse, type PaginationMeta, type PaginationOptions, type SortOptions, createClient };

package/dist/index.js

@@ -0,0 +1 @@
+var m=["documentId","key","label","order","is_active"];var C="order";function D(a){return a.map(([t,e])=>`${encodeURIComponent(t).replace(/%5B/gi,"[").replace(/%5D/gi,"]").replace(/%24/gi,"$")}=${encodeURIComponent(e)}`).join("&")}function h(a,t,e){var d,f,p,g;let r=[],n=((d=t.sort)==null?void 0:d.field)??e.defaultSortField,o=((f=t.sort)==null?void 0:f.order)??e.defaultSortOrder;r.push([`sort[${n}]`,o]);let l=((p=t.pagination)==null?void 0:p.page)??1,i=((g=t.pagination)==null?void 0:g.pageSize)??e.defaultPageSize;r.push(["pagination[page]",String(l)]),r.push(["pagination[pageSize]",String(i)]);let s=t.fields??e.defaultFields;return r.push(["fields",s.join(",")]),r.push(["filters[$and][0][groups][code][$containsi]",a]),t.activeOnly!==false&&r.push(["filters[$and][1][is_active][$eq]","true"]),D(r)}function c(a){return {baseUrl:a.baseUrl.replace(/\/$/,""),token:a.token,apiPath:a.apiPath??"/api/master-datas",defaultFields:a.defaultFields??m,defaultPageSize:a.defaultPageSize??100,defaultSortOrder:a.defaultSortOrder??"asc",defaultSortField:a.defaultSortField??C,timeout:a.timeout??1e4}}var u=class{config;constructor(t){if(!t.baseUrl)throw new Error("[master-data] baseUrl is required");if(!t.token)throw new Error("[master-data] token is required");this.config=c(t);}async fetch(t,e={}){if(!t)throw new Error("[master-data] groupCode is required");let r=h(t,e,this.config),n=`${this.config.baseUrl}${this.config.apiPath}?${r}`,o=new AbortController,l=setTimeout(()=>o.abort(),this.config.timeout),i;try{i=await fetch(n,{method:"GET",headers:{Authorization:`Bearer ${this.config.token}`,"Content-Type":"application/json"},signal:o.signal});}catch(s){throw s.name==="AbortError"?new Error(`[master-data] Request timed out after ${this.config.timeout}ms`):s}finally{clearTimeout(l);}if(!i.ok){let s=await i.text().catch(()=>"");throw new Error(`[master-data] API error ${i.status} ${i.statusText}: ${s}`)}return i.json()}async fetchAll(t,e={}){var l;let r=((l=e.pagination)==null?void 0:l.pageSize)??this.config.defaultPageSize,n=1,o=[];for(;;){let i=await this.fetch(t,{...e,pagination:{page:n,pageSize:r}});o.push(...i.data);let{pageCount:s}=i.meta.pagination;if(n>=s)break;n++;}return o}async getItems(t,e={}){return e.fetchAll?this.fetchAll(t,e):(await this.fetch(t,e)).data}updateConfig(t){let e=c({...this.config,...t});Object.assign(this.config,e);}};function S(a){return new u(a)}export{u as MasterDataClient,S as createClient};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@onagentic/master-data",
+  "version": "1.0.0",
+  "description": "Lightweight client for fetching master data from a Strapi-compatible API endpoint",
+  "keywords": [
+    "master-data",
+    "strapi",
+    "api-client"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@types/node": "^22.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/onagentic/master-data.git"
+  }
+}