@frontal-labs/data 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# @frontal-labs/data
+
+Client for the Frontal Data platform processing subdomains (`/v1/data/*`). Each
+subdomain is a distinct backend service exposed as a namespace with a shared
+`capabilities`/`health`/`info`/`runs` envelope:
+
+`aggregations`, `archival`, `enrichment`, `exports`, `normalization`, `quality`,
+`query`, `schemas`, `serving`, `streams`, `sync`, and `transformations`.
+
+> Datasets (ingest + catalog), pipelines, and lineage have dedicated packages:
+> `@frontal-labs/datasets`, `@frontal-labs/pipelines`, `@frontal-labs/lineage`.
+
+## Installation
+
+```bash
+npm install @frontal-labs/data
+```
+
+## Quick Start
+
+```ts
+import { data } from "@frontal-labs/data";
+
+// Resource subdomains share list/create/get/execute.
+const aggregations = await data.aggregations.list();
+const created = await data.quality.create({ name: "nulls-check" });
+const run = await data.quality.execute(created.id as string); // -> evaluations
+
+// Federated query and schema resolution.
+const rows = await data.query.federated({ sql: "select 1" });
+const schema = await data.schemas.resolve({ name: "users" });
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `FRONTAL_API_KEY` | Yes | — | Frontal API authentication key |
+| `FRONTAL_API_URL` | No | `https://api.frontal.dev/v1` | Base URL for the Frontal API |
+| `FRONTAL_ENV` | No | `development` | Runtime environment (`development`, `test`, `production`) |
+| `FRONTAL_DEBUG` | No | `false` | Enable debug logging |

package/dist/client.d.ts

@@ -0,0 +1,29 @@
+import { FrontalClient } from "@frontal-labs/core";
+import { DataSdk } from "./sdk";
+/**
+ * Configuration for creating a standalone Frontal Data client.
+ */
+export interface DataClientConfig {
+    /** Frontal API key. */
+    apiKey: string;
+    /** Base URL for the Data API. Defaults to {@link DEFAULT_DATA_BASE_URL}. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to {@link DEFAULT_TIMEOUT}. */
+    timeout?: number;
+    /** Maximum number of retries for failed requests. Defaults to {@link DEFAULT_MAX_RETRIES}. */
+    maxRetries?: number;
+}
+/**
+ * Creates a {@link DataSdk} client from a {@link FrontalClient} instance or a
+ * {@link DataClientConfig} configuration object.
+ *
+ * @param config - An existing `FrontalClient` or a config object with `apiKey`.
+ * @returns A configured `DataSdk` instance.
+ */
+export declare function createDataClient(config: DataClientConfig | FrontalClient): DataSdk;
+/**
+ * Convenience singleton proxy for the Frontal Data SDK.
+ * Lazily initialises from environment variables on first property access.
+ */
+export declare const data: DataSdk;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EAGd,MAAM,oBAAoB,CAAC;AAO5B,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAGhC;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,gBAAgB,GAAG,aAAa,GACvC,OAAO,CAAC;AAwBX;;;GAGG;AACH,eAAO,MAAM,IAAI,SAWf,CAAC"}

package/dist/constants.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Default base URL for Frontal Data services.
+ */
+export declare const DEFAULT_DATA_BASE_URL = "https://api.frontal.dev/v1";
+/**
+ * Package version.
+ */
+export declare const VERSION = "0.0.1";
+/**
+ * Default timeout.
+ */
+export declare const DEFAULT_TIMEOUT = 30000;
+/**
+ * Default max retry number.
+ */
+export declare const DEFAULT_MAX_RETRIES = 3;
+/**
+ * Default retry delay.
+ */
+export declare const DEFAULT_RETRY_DELAY = 1000;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,qBAAqB,+BAA+B,CAAC;AAElE;;GAEG;AACH,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B;;GAEG;AACH,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC;;GAEG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,mBAAmB,OAAO,CAAC"}

package/dist/index.cjs

@@ -0,0 +1,475 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_DATA_BASE_URL: () => DEFAULT_DATA_BASE_URL,
+  DataSdk: () => DataSdk,
+  VERSION: () => VERSION,
+  createDataClient: () => createDataClient,
+  data: () => data
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_core2 = require("@frontal-labs/core");
+
+// src/constants.ts
+var DEFAULT_DATA_BASE_URL = "https://api.frontal.dev/v1";
+var VERSION = "0.0.1";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_RETRY_DELAY = 1e3;
+
+// src/sdk.ts
+var import_core = require("@frontal-labs/core");
+var DataSdk = class {
+  /** Aggregation management subdomain. */
+  aggregations;
+  /** Archival policy subdomain. */
+  archival;
+  /** Enrichment profile subdomain. */
+  enrichment;
+  /** Data export subdomain. */
+  exports;
+  /** Normalization profile subdomain. */
+  normalization;
+  /** Data quality ruleset subdomain. */
+  quality;
+  /** Serving product subdomain. */
+  serving;
+  /** Stream management subdomain. */
+  streams;
+  /** Sync job subdomain. */
+  sync;
+  /** Transformation subdomain. */
+  transformations;
+  /** Federated query subdomain. */
+  query;
+  /** Schema registry subdomain. */
+  schemas;
+  /**
+   * @param http - The shared HTTP client used for all subdomain requests.
+   */
+  constructor(http) {
+    this.aggregations = new AggregationsNamespace(http);
+    this.archival = new ArchivalNamespace(http);
+    this.enrichment = new EnrichmentNamespace(http);
+    this.exports = new ExportsNamespace(http);
+    this.normalization = new NormalizationNamespace(http);
+    this.quality = new QualityNamespace(http);
+    this.serving = new ServingNamespace(http);
+    this.streams = new StreamsNamespace(http);
+    this.sync = new SyncNamespace(http);
+    this.transformations = new TransformationsNamespace(http);
+    this.query = new QueryNamespace(http);
+    this.schemas = new SchemasNamespace(http);
+  }
+};
+var SubdomainBase = class {
+  /**
+   * @param http - The shared HTTP client.
+   * @param base - The subdomain base path (e.g. `/data/aggregations`).
+   */
+  constructor(http, base) {
+    this.http = http;
+    this.base = base;
+  }
+  /** List available capabilities for this subdomain. */
+  capabilities() {
+    return this.http.get(`${this.base}/capabilities`);
+  }
+  /** Health check for this subdomain. */
+  health() {
+    return this.http.get(`${this.base}/health`);
+  }
+  /** Metadata about this subdomain service. */
+  info() {
+    return this.http.get(`${this.base}/info`);
+  }
+  /** List asynchronous runs, with optional cursor-based pagination. */
+  async runs(opts = {}) {
+    const raw = await this.http.get(`${this.base}/runs`, opts);
+    return (0, import_core.createPageResult)(
+      (0, import_core.asPagePayload)(raw),
+      (c) => this.runs({ ...opts, cursor: c })
+    );
+  }
+  /** Create a new asynchronous run. */
+  createRun(input) {
+    return this.http.post(`${this.base}/runs`, input);
+  }
+  /** Get a single run by its ID. */
+  run(runId) {
+    return this.http.get(`${this.base}/runs/${runId}`);
+  }
+};
+var AggregationsNamespace = class extends SubdomainBase {
+  constructor(http) {
+    super(http, "/data/aggregations");
+  }
+  /** List all aggregation definitions. */
+  async list(opts = {}) {
+    const raw = await this.http.get("/data/aggregations/aggregations", opts);
+    return (0, import_core.createPageResult)(
+      (0, import_core.asPagePayload)(raw),
+      (c) => this.list({ ...opts, cursor: c })
+    );
+  }
+  /** Create a new aggregation definition. */
+  create(body) {
+    return this.http.post("/data/aggregations/aggregations", body);
+  }
+  /** Get a single aggregation definition by ID. */
+  get(id) {
+    return this.http.get(`/data/aggregations/aggregations/${id}`);
+  }
+  /** Execute an aggregation and return a run result. */
+  execute(id, body = {}) {
+    return this.http.post(
+      `/data/aggregations/aggregations/${id}/executions`,
+      body
+    );
+  }
+};
+var ArchivalNamespace = class extends SubdomainBase {
+  constructor(http) {
+    super(http, "/data/archival");
+  }
+  /** List all archival policies. */
+  async list(opts = {}) {
+    const raw = await this.http.get("/data/archival/archival/policies", opts);
+    return (0, import_core.createPageResult)(
+      (0, import_core.asPagePayload)(raw),
+      (c) => this.list({ ...opts, cursor: c })
+    );
+  }
+  /** Create a new archival policy. */
+  create(body) {
+    return this.http.post("/data/archival/archival/policies", body);
+  }
+  /** Get a single archival policy by ID. */
+  get(id) {
+    return this.http.get(`/data/archival/archival/policies/${id}`);
+  }
+  /** Execute an archival policy. */
+  execute(id, body = {}) {
+    return this.http.post(
+      `/data/archival/archival/policies/${id}/executions`,
+      body
+    );
+  }
+};
+var EnrichmentNamespace = class extends SubdomainBase {
+  constructor(http) {
+    super(http, "/data/enrichment");
+  }
+  /** List all enrichment profiles. */
+  async list(opts = {}) {
+    const raw = await this.http.get(
+      "/data/enrichment/enrichment/profiles",
+      opts
+    );
+    return (0, import_core.createPageResult)(
+      (0, import_core.asPagePayload)(raw),
+      (c) => this.list({ ...opts, cursor: c })
+    );
+  }
+  /** Create a new enrichment profile. */
+  create(body) {
+    return this.http.post("/data/enrichment/enrichment/profiles", body);
+  }
+  /** Get a single enrichment profile by ID. */
+  get(id) {
+    return this.http.get(`/data/enrichment/enrichment/profiles/${id}`);
+  }
+  /** Execute an enrichment profile. */
+  execute(id, body = {}) {
+    return this.http.post(
+      `/data/enrichment/enrichment/profiles/${id}/executions`,
+      body
+    );
+  }
+};
+var ExportsNamespace = class extends SubdomainBase {
+  constructor(http) {
+    super(http, "/data/exports");
+  }
+  /** List all exports. */
+  async list(opts = {}) {
+    const raw = await this.http.get("/data/exports/exports", opts);
+    return (0, import_core.createPageResult)(
+      (0, import_core.asPagePayload)(raw),
+      (c) => this.list({ ...opts, cursor: c })
+    );
+  }
+  /** Create a new export job. */
+  create(body) {
+    return this.http.post("/data/exports/exports", body);
+  }
+  /** Get a single export by ID. */
+  get(id) {
+    return this.http.get(`/data/exports/exports/${id}`);
+  }
+  /** Execute an export job. */
+  execute(id, body = {}) {
+    return this.http.post(`/data/exports/exports/${id}/executions`, body);
+  }
+};
+var NormalizationNamespace = class extends SubdomainBase {
+  constructor(http) {
+    super(http, "/data/normalization");
+  }
+  /** List all normalization profiles. */
+  async list(opts = {}) {
+    const raw = await this.http.get(
+      "/data/normalization/normalization/profiles",
+      opts
+    );
+    return (0, import_core.createPageResult)(
+      (0, import_core.asPagePayload)(raw),
+      (c) => this.list({ ...opts, cursor: c })
+    );
+  }
+  /** Create a new normalization profile. */
+  create(body) {
+    return this.http.post("/data/normalization/normalization/profiles", body);
+  }
+  /** Get a single normalization profile by ID. */
+  get(id) {
+    return this.http.get(`/data/normalization/normalization/profiles/${id}`);
+  }
+  /** Execute a normalization profile. */
+  execute(id, body = {}) {
+    return this.http.post(
+      `/data/normalization/normalization/profiles/${id}/executions`,
+      body
+    );
+  }
+};
+var QualityNamespace = class extends SubdomainBase {
+  constructor(http) {
+    super(http, "/data/quality");
+  }
+  /** List all quality rulesets. */
+  async list(opts = {}) {
+    const raw = await this.http.get("/data/quality/quality/rulesets", opts);
+    return (0, import_core.createPageResult)(
+      (0, import_core.asPagePayload)(raw),
+      (c) => this.list({ ...opts, cursor: c })
+    );
+  }
+  /** Create a new quality ruleset. */
+  create(body) {
+    return this.http.post("/data/quality/quality/rulesets", body);
+  }
+  /** Get a single quality ruleset by ID. */
+  get(id) {
+    return this.http.get(`/data/quality/quality/rulesets/${id}`);
+  }
+  /** Evaluate a ruleset. */
+  execute(id, body = {}) {
+    return this.http.post(
+      `/data/quality/quality/rulesets/${id}/evaluations`,
+      body
+    );
+  }
+};
+var ServingNamespace = class extends SubdomainBase {
+  constructor(http) {
+    super(http, "/data/serving");
+  }
+  /** List all serving products. */
+  async list(opts = {}) {
+    const raw = await this.http.get("/data/serving/serving/products", opts);
+    return (0, import_core.createPageResult)(
+      (0, import_core.asPagePayload)(raw),
+      (c) => this.list({ ...opts, cursor: c })
+    );
+  }
+  /** Create a new serving product. */
+  create(body) {
+    return this.http.post("/data/serving/serving/products", body);
+  }
+  /** Get a single serving product by ID. */
+  get(id) {
+    return this.http.get(`/data/serving/serving/products/${id}`);
+  }
+  /** Refresh a serving product. */
+  execute(id, body = {}) {
+    return this.http.post(
+      `/data/serving/serving/products/${id}/refreshes`,
+      body
+    );
+  }
+};
+var StreamsNamespace = class extends SubdomainBase {
+  constructor(http) {
+    super(http, "/data/streams");
+  }
+  /** List all streams. */
+  async list(opts = {}) {
+    const raw = await this.http.get("/data/streams/streams", opts);
+    return (0, import_core.createPageResult)(
+      (0, import_core.asPagePayload)(raw),
+      (c) => this.list({ ...opts, cursor: c })
+    );
+  }
+  /** Create a new stream. */
+  create(body) {
+    return this.http.post("/data/streams/streams", body);
+  }
+  /** Get a single stream by ID. */
+  get(id) {
+    return this.http.get(`/data/streams/streams/${id}`);
+  }
+  /** Trigger deliveries for a stream. */
+  execute(id, body = {}) {
+    return this.http.post(`/data/streams/streams/${id}/deliveries`, body);
+  }
+};
+var SyncNamespace = class extends SubdomainBase {
+  constructor(http) {
+    super(http, "/data/sync");
+  }
+  /** List all sync jobs. */
+  async list(opts = {}) {
+    const raw = await this.http.get("/data/sync/sync/jobs", opts);
+    return (0, import_core.createPageResult)(
+      (0, import_core.asPagePayload)(raw),
+      (c) => this.list({ ...opts, cursor: c })
+    );
+  }
+  /** Create a new sync job. */
+  create(body) {
+    return this.http.post("/data/sync/sync/jobs", body);
+  }
+  /** Get a single sync job by ID. */
+  get(id) {
+    return this.http.get(`/data/sync/sync/jobs/${id}`);
+  }
+  /** Execute a sync job. */
+  execute(id, body = {}) {
+    return this.http.post(`/data/sync/sync/jobs/${id}/executions`, body);
+  }
+};
+var TransformationsNamespace = class extends SubdomainBase {
+  constructor(http) {
+    super(http, "/data/transformations");
+  }
+  /** List all transformations. */
+  async list(opts = {}) {
+    const raw = await this.http.get(
+      "/data/transformations/transformations",
+      opts
+    );
+    return (0, import_core.createPageResult)(
+      (0, import_core.asPagePayload)(raw),
+      (c) => this.list({ ...opts, cursor: c })
+    );
+  }
+  /** Create a new transformation. */
+  create(body) {
+    return this.http.post("/data/transformations/transformations", body);
+  }
+  /** Get a single transformation by ID. */
+  get(id) {
+    return this.http.get(`/data/transformations/transformations/${id}`);
+  }
+  /** Execute a transformation. */
+  execute(id, body = {}) {
+    return this.http.post(
+      `/data/transformations/transformations/${id}/executions`,
+      body
+    );
+  }
+};
+var QueryNamespace = class extends SubdomainBase {
+  constructor(http) {
+    super(http, "/data/query");
+  }
+  /** Execute a federated query across multiple data sources. */
+  federated(body) {
+    return this.http.post("/data/query/query/federated", body);
+  }
+};
+var SchemasNamespace = class extends SubdomainBase {
+  constructor(http) {
+    super(http, "/data/schemas");
+  }
+  /** List all registered schemas. */
+  async list(opts = {}) {
+    const raw = await this.http.get("/data/schemas/schemas", opts);
+    return (0, import_core.createPageResult)(
+      (0, import_core.asPagePayload)(raw),
+      (c) => this.list({ ...opts, cursor: c })
+    );
+  }
+  /** Register a new schema. */
+  create(body) {
+    return this.http.post("/data/schemas/schemas", body);
+  }
+  /** Resolve a schema reference to its definition. */
+  resolve(body) {
+    return this.http.post("/data/schemas/schemas/resolve", body);
+  }
+  /** Get a registered schema by reference. */
+  get(schemaRef) {
+    return this.http.get(`/data/schemas/schemas/${schemaRef}`);
+  }
+};
+
+// src/client.ts
+var import_core3 = require("@frontal-labs/core");
+function createDataClient(clientOrConfig) {
+  if (clientOrConfig instanceof import_core2.FrontalClient) {
+    return new DataSdk(clientOrConfig.httpClient);
+  }
+  const http = new import_core2.HttpClient({
+    apiKey: clientOrConfig.apiKey,
+    baseUrl: clientOrConfig.baseUrl ?? import_core3.env.FRONTAL_API_URL ?? DEFAULT_DATA_BASE_URL,
+    timeout: clientOrConfig.timeout ?? DEFAULT_TIMEOUT,
+    maxRetries: clientOrConfig.maxRetries ?? DEFAULT_MAX_RETRIES,
+    retryDelay: DEFAULT_RETRY_DELAY,
+    headers: {},
+    environment: import_core3.env.FRONTAL_ENV,
+    debug: import_core3.env.FRONTAL_DEBUG ?? false
+  });
+  return new DataSdk(http);
+}
+var _dataCache;
+var data = new Proxy({}, {
+  get(_t, prop) {
+    if (!_dataCache) {
+      _dataCache = createDataClient((0, import_core2.getDefaultClient)());
+    }
+    const inst = _dataCache;
+    const val = inst[prop];
+    return typeof val === "function" ? val.bind(inst) : val;
+  }
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_DATA_BASE_URL,
+  DataSdk,
+  VERSION,
+  createDataClient,
+  data
+});

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @frontal-labs/data
+ *
+ * Query, aggregate, enrich, transform, and serve data on Frontal.
+ */
+export { createDataClient, data, type DataClientConfig } from "./client";
+export { DEFAULT_DATA_BASE_URL, VERSION } from "./constants";
+export { DataSdk } from "./sdk";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,KAAK,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC"}