@helebba/sdk 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# Helebba SDK
+
+Cliente minimo para leer inventario desde aplicaciones externas.
+
+```ts
+import { createHelebbaClient } from '@hlb/sdk';
+
+const helebba = createHelebbaClient({
+  apiKey: process.env.HELEBBA_API_KEY!,
+});
+
+const products = await helebba.products.list({ search: 'camisa' });
+const brands = await helebba.brands.list();
+const categories = await helebba.categories.list();
+```
+
+Para desarrollo, la API key debe incluir organizacion y scope:
+
+```txt
+DEV_API_KEYS="hlb_dev_xxxxxxxxxxxxxxxxxxxx:id=sdk-dev,organizationId=<org-id>,scopes=inventory:read,products=GSDK"
+```

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+type OffsetPageInfo = {
+    page: number;
+    pages: number;
+    pageSize: number;
+    totalItems: number;
+    hasPreviousPage: boolean;
+    hasNextPage: boolean;
+    previousPage: number | null;
+    nextPage: number | null;
+};
+type OffsetPaginatedResult<T> = {
+    kind: 'offset';
+    count: number;
+    items: T[];
+    pageInfo: OffsetPageInfo;
+};
+type ListParams = {
+    page?: number;
+    limit?: number;
+    search?: string;
+};
+type HelebbaClientOptions = {
+    apiKey: string;
+    baseUrl?: string;
+    fetcher?: typeof fetch;
+};
+type HelebbaClient = {
+    products: {
+        list: (params?: ListParams) => Promise<OffsetPaginatedResult<Product>>;
+        get: (productId: string) => Promise<Product>;
+    };
+    brands: {
+        list: (params?: ListParams) => Promise<OffsetPaginatedResult<InventoryBrand>>;
+    };
+    categories: {
+        list: (params?: ListParams) => Promise<OffsetPaginatedResult<Category>>;
+    };
+};
+type Product = Record<string, unknown> & {
+    id: string;
+    name: string;
+    sku?: string;
+    description?: string;
+};
+type InventoryBrand = Record<string, unknown> & {
+    id: string;
+    name: string;
+    description?: string;
+};
+type Category = Record<string, unknown> & {
+    id: string;
+    name: string;
+    description?: string;
+};
+
+declare const createHelebbaClient: (options: HelebbaClientOptions) => HelebbaClient;
+
+type HelebbaApiError = Error & {
+    status: number;
+    body: unknown;
+};
+declare const createHelebbaApiError: (message: string, status: number, body: unknown) => HelebbaApiError;
+
+export { type Category, type HelebbaApiError, type HelebbaClient, type HelebbaClientOptions, type InventoryBrand, type ListParams, type OffsetPaginatedResult, type Product, createHelebbaApiError, createHelebbaClient };

package/dist/index.mjs

@@ -0,0 +1,68 @@
+// src/http.ts
+var createHelebbaApiError = (message, status, body) => {
+  const error = new Error(message);
+  error.name = "HelebbaApiError";
+  error.status = status;
+  error.body = body;
+  return error;
+};
+var trimTrailingSlash = (value) => value.replace(/\/+$/, "");
+var DEFAULT_BASE_URL = "https://api.helebba.com/api/v1";
+var appendQuery = (url, query) => {
+  if (!query) return;
+  if (query.page !== void 0) url.searchParams.set("page", String(query.page));
+  if (query.limit !== void 0) url.searchParams.set("limit", String(query.limit));
+  if (query.search) url.searchParams.set("search", query.search);
+};
+var createHttpClient = (options) => {
+  if (!options.apiKey) throw new Error("Helebba SDK requires apiKey");
+  const apiKey = options.apiKey;
+  const baseUrl = trimTrailingSlash(options.baseUrl ?? DEFAULT_BASE_URL);
+  const fetcher = options.fetcher ?? fetch;
+  return {
+    get: async (path, options2 = {}) => {
+      const url = new URL(`${baseUrl}${path}`);
+      appendQuery(url, options2.query);
+      const timestamp = Date.now().toString();
+      const response = await fetcher(url, {
+        method: "GET",
+        headers: {
+          "api-key": apiKey,
+          "x-timestamp": timestamp,
+          "x-path": url.pathname,
+          "x-client-user-agent": "GSDK/0.1.0 (node)",
+          Accept: "application/json"
+        }
+      });
+      const contentType = response.headers.get("content-type") ?? "";
+      const body = contentType.includes("application/json") ? await response.json() : await response.text();
+      if (!response.ok) {
+        const message = typeof body === "object" && body && "message" in body ? String(body.message) : `Helebba API request failed with status ${response.status}`;
+        throw createHelebbaApiError(message, response.status, body);
+      }
+      return body;
+    }
+  };
+};
+
+// src/client.ts
+var createHelebbaClient = (options) => {
+  const http = createHttpClient(options);
+  return {
+    products: {
+      list: (params = {}) => http.get("/sdk/products", { query: params }),
+      get: (productId) => http.get(`/sdk/products/${encodeURIComponent(productId)}`)
+    },
+    brands: {
+      list: (params = {}) => http.get("/sdk/brands", { query: params })
+    },
+    categories: {
+      list: (params = {}) => http.get("/sdk/categories", { query: params })
+    }
+  };
+};
+export {
+  createHelebbaApiError,
+  createHelebbaClient
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/http.ts","../src/client.ts"],"sourcesContent":["import type { HelebbaClientOptions, ListParams } from './types';\n\ntype RequestOptions = {\n  query?: ListParams;\n};\n\nexport type HelebbaApiError = Error & {\n  status: number;\n  body: unknown;\n};\n\nexport const createHelebbaApiError = (\n  message: string,\n  status: number,\n  body: unknown,\n): HelebbaApiError => {\n  const error = new Error(message) as HelebbaApiError;\n  error.name = 'HelebbaApiError';\n  error.status = status;\n  error.body = body;\n  return error;\n};\n\nconst trimTrailingSlash = (value: string) => value.replace(/\\/+$/, '');\nconst DEFAULT_BASE_URL = 'https://api.helebba.com/api/v1';\n\nconst appendQuery = (url: URL, query: ListParams | undefined) => {\n  if (!query) return;\n\n  if (query.page !== undefined) url.searchParams.set('page', String(query.page));\n  if (query.limit !== undefined) url.searchParams.set('limit', String(query.limit));\n  if (query.search) url.searchParams.set('search', query.search);\n};\n\nexport type HttpClient = {\n  get: <T>(path: string, options?: RequestOptions) => Promise<T>;\n};\n\nexport const createHttpClient = (options: HelebbaClientOptions): HttpClient => {\n  if (!options.apiKey) throw new Error('Helebba SDK requires apiKey');\n\n  const apiKey = options.apiKey;\n  const baseUrl = trimTrailingSlash(options.baseUrl ?? DEFAULT_BASE_URL);\n  const fetcher = options.fetcher ?? fetch;\n\n  return {\n    get: async <T>(path: string, options: RequestOptions = {}): Promise<T> => {\n      const url = new URL(`${baseUrl}${path}`);\n      appendQuery(url, options.query);\n\n      const timestamp = Date.now().toString();\n\n      const response = await fetcher(url, {\n        method: 'GET',\n        headers: {\n          'api-key': apiKey,\n          'x-timestamp': timestamp,\n          'x-path': url.pathname,\n          'x-client-user-agent': 'GSDK/0.1.0 (node)',\n          Accept: 'application/json',\n        },\n      });\n\n      const contentType = response.headers.get('content-type') ?? '';\n      const body = contentType.includes('application/json')\n        ? await response.json()\n        : await response.text();\n\n      if (!response.ok) {\n        const message =\n          typeof body === 'object' && body && 'message' in body\n            ? String((body as { message: unknown }).message)\n            : `Helebba API request failed with status ${response.status}`;\n\n        throw createHelebbaApiError(message, response.status, body);\n      }\n\n      return body as T;\n    },\n  };\n};\n","import { createHttpClient } from './http';\nimport type {\n  Category,\n  HelebbaClient,\n  HelebbaClientOptions,\n  InventoryBrand,\n  OffsetPaginatedResult,\n  Product,\n} from './types';\n\nexport const createHelebbaClient = (options: HelebbaClientOptions): HelebbaClient => {\n  const http = createHttpClient(options);\n\n  return {\n    products: {\n      list: (params = {}) =>\n        http.get<OffsetPaginatedResult<Product>>('/sdk/products', { query: params }),\n      get: (productId) => http.get<Product>(`/sdk/products/${encodeURIComponent(productId)}`),\n    },\n    brands: {\n      list: (params = {}) =>\n        http.get<OffsetPaginatedResult<InventoryBrand>>('/sdk/brands', { query: params }),\n    },\n    categories: {\n      list: (params = {}) =>\n        http.get<OffsetPaginatedResult<Category>>('/sdk/categories', { query: params }),\n    },\n  };\n};\n"],"mappings":";AAWO,IAAM,wBAAwB,CACnC,SACA,QACA,SACoB;AACpB,QAAM,QAAQ,IAAI,MAAM,OAAO;AAC/B,QAAM,OAAO;AACb,QAAM,SAAS;AACf,QAAM,OAAO;AACb,SAAO;AACT;AAEA,IAAM,oBAAoB,CAAC,UAAkB,MAAM,QAAQ,QAAQ,EAAE;AACrE,IAAM,mBAAmB;AAEzB,IAAM,cAAc,CAAC,KAAU,UAAkC;AAC/D,MAAI,CAAC,MAAO;AAEZ,MAAI,MAAM,SAAS,OAAW,KAAI,aAAa,IAAI,QAAQ,OAAO,MAAM,IAAI,CAAC;AAC7E,MAAI,MAAM,UAAU,OAAW,KAAI,aAAa,IAAI,SAAS,OAAO,MAAM,KAAK,CAAC;AAChF,MAAI,MAAM,OAAQ,KAAI,aAAa,IAAI,UAAU,MAAM,MAAM;AAC/D;AAMO,IAAM,mBAAmB,CAAC,YAA8C;AAC7E,MAAI,CAAC,QAAQ,OAAQ,OAAM,IAAI,MAAM,6BAA6B;AAElE,QAAM,SAAS,QAAQ;AACvB,QAAM,UAAU,kBAAkB,QAAQ,WAAW,gBAAgB;AACrE,QAAM,UAAU,QAAQ,WAAW;AAEnC,SAAO;AAAA,IACL,KAAK,OAAU,MAAcA,WAA0B,CAAC,MAAkB;AACxE,YAAM,MAAM,IAAI,IAAI,GAAG,OAAO,GAAG,IAAI,EAAE;AACvC,kBAAY,KAAKA,SAAQ,KAAK;AAE9B,YAAM,YAAY,KAAK,IAAI,EAAE,SAAS;AAEtC,YAAM,WAAW,MAAM,QAAQ,KAAK;AAAA,QAClC,QAAQ;AAAA,QACR,SAAS;AAAA,UACP,WAAW;AAAA,UACX,eAAe;AAAA,UACf,UAAU,IAAI;AAAA,UACd,uBAAuB;AAAA,UACvB,QAAQ;AAAA,QACV;AAAA,MACF,CAAC;AAED,YAAM,cAAc,SAAS,QAAQ,IAAI,cAAc,KAAK;AAC5D,YAAM,OAAO,YAAY,SAAS,kBAAkB,IAChD,MAAM,SAAS,KAAK,IACpB,MAAM,SAAS,KAAK;AAExB,UAAI,CAAC,SAAS,IAAI;AAChB,cAAM,UACJ,OAAO,SAAS,YAAY,QAAQ,aAAa,OAC7C,OAAQ,KAA8B,OAAO,IAC7C,0CAA0C,SAAS,MAAM;AAE/D,cAAM,sBAAsB,SAAS,SAAS,QAAQ,IAAI;AAAA,MAC5D;AAEA,aAAO;AAAA,IACT;AAAA,EACF;AACF;;;ACtEO,IAAM,sBAAsB,CAAC,YAAiD;AACnF,QAAM,OAAO,iBAAiB,OAAO;AAErC,SAAO;AAAA,IACL,UAAU;AAAA,MACR,MAAM,CAAC,SAAS,CAAC,MACf,KAAK,IAAoC,iBAAiB,EAAE,OAAO,OAAO,CAAC;AAAA,MAC7E,KAAK,CAAC,cAAc,KAAK,IAAa,iBAAiB,mBAAmB,SAAS,CAAC,EAAE;AAAA,IACxF;AAAA,IACA,QAAQ;AAAA,MACN,MAAM,CAAC,SAAS,CAAC,MACf,KAAK,IAA2C,eAAe,EAAE,OAAO,OAAO,CAAC;AAAA,IACpF;AAAA,IACA,YAAY;AAAA,MACV,MAAM,CAAC,SAAS,CAAC,MACf,KAAK,IAAqC,mBAAmB,EAAE,OAAO,OAAO,CAAC;AAAA,IAClF;AAAA,EACF;AACF;","names":["options"]}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@helebba/sdk",
+  "version": "0.1.0",
+  "description": "Helebba SDK for external applications.",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "scripts": {
+    "dev": "NODE_OPTIONS='--conditions=development' tsup --config tsup.dev.config.ts --watch",
+    "build": "tsup",
+    "check-types": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "devDependencies": {
+    "@hlb/tooling": "workspace:*",
+    "@types/node": "catalog:",
+    "tsup": "catalog:",
+    "typescript": "catalog:"
+  }
+}

package/src/client.ts

@@ -0,0 +1,29 @@
+import { createHttpClient } from './http';
+import type {
+  Category,
+  HelebbaClient,
+  HelebbaClientOptions,
+  InventoryBrand,
+  OffsetPaginatedResult,
+  Product,
+} from './types';
+
+export const createHelebbaClient = (options: HelebbaClientOptions): HelebbaClient => {
+  const http = createHttpClient(options);
+
+  return {
+    products: {
+      list: (params = {}) =>
+        http.get<OffsetPaginatedResult<Product>>('/sdk/products', { query: params }),
+      get: (productId) => http.get<Product>(`/sdk/products/${encodeURIComponent(productId)}`),
+    },
+    brands: {
+      list: (params = {}) =>
+        http.get<OffsetPaginatedResult<InventoryBrand>>('/sdk/brands', { query: params }),
+    },
+    categories: {
+      list: (params = {}) =>
+        http.get<OffsetPaginatedResult<Category>>('/sdk/categories', { query: params }),
+    },
+  };
+};

package/src/http.ts

@@ -0,0 +1,81 @@
+import type { HelebbaClientOptions, ListParams } from './types';
+
+type RequestOptions = {
+  query?: ListParams;
+};
+
+export type HelebbaApiError = Error & {
+  status: number;
+  body: unknown;
+};
+
+export const createHelebbaApiError = (
+  message: string,
+  status: number,
+  body: unknown,
+): HelebbaApiError => {
+  const error = new Error(message) as HelebbaApiError;
+  error.name = 'HelebbaApiError';
+  error.status = status;
+  error.body = body;
+  return error;
+};
+
+const trimTrailingSlash = (value: string) => value.replace(/\/+$/, '');
+const DEFAULT_BASE_URL = 'https://api.helebba.com/api/v1';
+
+const appendQuery = (url: URL, query: ListParams | undefined) => {
+  if (!query) return;
+
+  if (query.page !== undefined) url.searchParams.set('page', String(query.page));
+  if (query.limit !== undefined) url.searchParams.set('limit', String(query.limit));
+  if (query.search) url.searchParams.set('search', query.search);
+};
+
+export type HttpClient = {
+  get: <T>(path: string, options?: RequestOptions) => Promise<T>;
+};
+
+export const createHttpClient = (options: HelebbaClientOptions): HttpClient => {
+  if (!options.apiKey) throw new Error('Helebba SDK requires apiKey');
+
+  const apiKey = options.apiKey;
+  const baseUrl = trimTrailingSlash(options.baseUrl ?? DEFAULT_BASE_URL);
+  const fetcher = options.fetcher ?? fetch;
+
+  return {
+    get: async <T>(path: string, options: RequestOptions = {}): Promise<T> => {
+      const url = new URL(`${baseUrl}${path}`);
+      appendQuery(url, options.query);
+
+      const timestamp = Date.now().toString();
+
+      const response = await fetcher(url, {
+        method: 'GET',
+        headers: {
+          'api-key': apiKey,
+          'x-timestamp': timestamp,
+          'x-path': url.pathname,
+          'x-client-user-agent': 'GSDK/0.1.0 (node)',
+          Accept: 'application/json',
+        },
+      });
+
+      const contentType = response.headers.get('content-type') ?? '';
+      const body = contentType.includes('application/json')
+        ? await response.json()
+        : await response.text();
+
+      if (!response.ok) {
+        const message =
+          typeof body === 'object' && body && 'message' in body
+            ? String((body as { message: unknown }).message)
+            : `Helebba API request failed with status ${response.status}`;
+
+        throw createHelebbaApiError(message, response.status, body);
+      }
+
+      return body as T;
+    },
+  };
+};

package/src/index.ts

@@ -0,0 +1,12 @@
+export { createHelebbaClient } from './client';
+export { createHelebbaApiError } from './http';
+export type { HelebbaApiError } from './http';
+export type {
+  Category,
+  HelebbaClient,
+  HelebbaClientOptions,
+  InventoryBrand,
+  ListParams,
+  OffsetPaginatedResult,
+  Product,
+} from './types';

package/src/types.ts

@@ -0,0 +1,61 @@
+export type OffsetPageInfo = {
+  page: number;
+  pages: number;
+  pageSize: number;
+  totalItems: number;
+  hasPreviousPage: boolean;
+  hasNextPage: boolean;
+  previousPage: number | null;
+  nextPage: number | null;
+};
+
+export type OffsetPaginatedResult<T> = {
+  kind: 'offset';
+  count: number;
+  items: T[];
+  pageInfo: OffsetPageInfo;
+};
+
+export type ListParams = {
+  page?: number;
+  limit?: number;
+  search?: string;
+};
+
+export type HelebbaClientOptions = {
+  apiKey: string;
+  baseUrl?: string;
+  fetcher?: typeof fetch;
+};
+
+export type HelebbaClient = {
+  products: {
+    list: (params?: ListParams) => Promise<OffsetPaginatedResult<Product>>;
+    get: (productId: string) => Promise<Product>;
+  };
+  brands: {
+    list: (params?: ListParams) => Promise<OffsetPaginatedResult<InventoryBrand>>;
+  };
+  categories: {
+    list: (params?: ListParams) => Promise<OffsetPaginatedResult<Category>>;
+  };
+};
+
+export type Product = Record<string, unknown> & {
+  id: string;
+  name: string;
+  sku?: string;
+  description?: string;
+};
+
+export type InventoryBrand = Record<string, unknown> & {
+  id: string;
+  name: string;
+  description?: string;
+};
+
+export type Category = Record<string, unknown> & {
+  id: string;
+  name: string;
+  description?: string;
+};

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@hlb/tooling/tsconfig/base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "lib": ["ES2022", "DOM"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  outExtension: () => ({ js: '.mjs' }),
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  target: 'es2022',
+});

package/tsup.dev.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  outExtension: () => ({ js: '.mjs' }),
+  dts: false,
+  sourcemap: true,
+  clean: true,
+  target: 'es2022',
+});