@frontal-labs/ontology 0.0.1

package/README.md

@@ -0,0 +1,32 @@
+# @frontal-labs/ontology
+
+Ontology and model management APIs for schema, rules, and migrations.
+
+## Installation
+
+```bash
+bun add @frontal-labs/ontology @frontal-labs/core
+```
+
+## Usage
+
+```ts
+import { FrontalClient } from "@frontal-labs/core";
+import { createOntologyClient } from "@frontal-labs/ontology";
+
+const client = new FrontalClient({
+  apiKey: process.env.FRONTAL_API_KEY!,
+  baseUrl: process.env.FRONTAL_API_URL ?? "https://api.frontal.dev/v1",
+});
+
+const ontology = createOntologyClient(client);
+
+const models = await ontology.list({ limit: 10 });
+await ontology.create({ name: "invoice", fields: [{ name: "amount", type: "number", required: true }] });
+```
+
+## Configuration
+
+- `FRONTAL_API_KEY`
+- `FRONTAL_ONTOLOGY_API_URL` (optional)
+- `FRONTAL_API_URL` (fallback)

package/dist/constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Default base URL for Frontal Ontology services.
+ */
+export declare const DEFAULT_ONTOLOGY_BASE_URL = "https://api.frontal.dev/v1";
+/**
+ * Package version.
+ */
+export declare const VERSION = "0.0.1";
+//# 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,yBAAyB,+BAA+B,CAAC;AAEtE;;GAEG;AACH,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { FrontalClient } from "@frontal-labs/core";
+import { OntologyService } from "./service";
+/** Config for standalone usage without @frontal-labs/core */
+export interface OntologyClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+}
+/** Create from a FrontalClient instance */
+export declare function createOntologyClient(client: FrontalClient): OntologyService;
+/** Create standalone with just config */
+export declare function createOntologyClient(config: OntologyClientConfig): OntologyService;
+export declare const ontology: OntologyService;
+export * from "./schemas";
+export { OntologyService } from "./service";
+//# 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,OAAO,EAAE,aAAa,EAAgC,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,6DAA6D;AAC7D,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,2CAA2C;AAC3C,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe,CAAC;AAC7E,yCAAyC;AACzC,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,oBAAoB,GAC3B,eAAe,CAAC;AAyBnB,eAAO,MAAM,QAAQ,iBAAgD,CAAC;AAEtE,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,468 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+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);
+var __async = (__this, __arguments, generator) => {
+  return new Promise((resolve, reject) => {
+    var fulfilled = (value) => {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var rejected = (value) => {
+      try {
+        step(generator.throw(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
+    step((generator = generator.apply(__this, __arguments)).next());
+  });
+};
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FieldDefinitionSchema: () => FieldDefinitionSchema,
+  FieldTypeSchema: () => FieldTypeSchema,
+  IndexDefinitionSchema: () => IndexDefinitionSchema,
+  MigrationPlanSchema: () => MigrationPlanSchema,
+  MixinDefinitionSchema: () => MixinDefinitionSchema,
+  ModelDefinitionSchema: () => ModelDefinitionSchema,
+  ModelSchema: () => ModelSchema,
+  OntologyService: () => OntologyService,
+  RelationshipDefinitionSchema: () => RelationshipDefinitionSchema,
+  RelationshipTypeSchema: () => RelationshipTypeSchema,
+  RuleDefinitionSchema: () => RuleDefinitionSchema,
+  SemanticMetadataSchema: () => SemanticMetadataSchema,
+  SubstrateRoutingSchema: () => SubstrateRoutingSchema,
+  createOntologyClient: () => createOntologyClient,
+  ontology: () => ontology
+});
+module.exports = __toCommonJS(index_exports);
+var import_core3 = require("@frontal-labs/core");
+
+// src/service.ts
+var import_core2 = require("@frontal-labs/core");
+
+// src/schemas.ts
+var import_core = require("@frontal-labs/core");
+var import_zod = require("zod");
+var FieldTypeSchema = import_zod.z.enum([
+  "string",
+  "integer",
+  "float",
+  "boolean",
+  "uuid",
+  "timestamp",
+  "currency",
+  "json",
+  "array",
+  "enum",
+  "vector",
+  "text"
+]);
+var RelationshipTypeSchema = import_zod.z.enum([
+  "hasOne",
+  "hasMany",
+  "belongsTo",
+  "manyToMany"
+]);
+var FieldDefinitionSchema = import_zod.z.object({
+  type: FieldTypeSchema,
+  required: import_zod.z.boolean().default(false),
+  primary: import_zod.z.boolean().default(false),
+  unique: import_zod.z.boolean().default(false),
+  default: import_zod.z.unknown().optional(),
+  substrate: import_zod.z.string().optional(),
+  computed: import_zod.z.boolean().optional(),
+  derivedBy: import_zod.z.string().optional(),
+  cache: import_zod.z.object({
+    ttl: import_zod.z.string()
+  }).optional(),
+  auto: import_zod.z.boolean().optional(),
+  enum: import_zod.z.array(import_zod.z.string()).optional(),
+  dimensions: import_zod.z.number().int().optional(),
+  items: import_zod.z.string().optional(),
+  description: import_zod.z.string().optional()
+}).passthrough();
+var RelationshipDefinitionSchema = import_zod.z.object({
+  name: import_zod.z.string().optional(),
+  type: RelationshipTypeSchema,
+  targetEntity: import_zod.z.string(),
+  foreignKey: import_zod.z.string().optional(),
+  substrate: import_zod.z.string().optional(),
+  cascade: import_zod.z.object({
+    delete: import_zod.z.enum(["hard", "soft", "restrict", "nullify"]),
+    update: import_zod.z.enum(["cascade", "restrict"])
+  }).optional(),
+  computed: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional(),
+  description: import_zod.z.string().optional()
+}).passthrough();
+var SubstrateRoutingSchema = import_zod.z.object({
+  operational: import_zod.z.string().optional(),
+  analytical: import_zod.z.string().optional(),
+  semantic: import_zod.z.string().optional(),
+  cache: import_zod.z.string().optional()
+}).passthrough();
+var SemanticMetadataSchema = import_zod.z.object({
+  description: import_zod.z.string().optional(),
+  lifecycle: import_zod.z.array(import_zod.z.string()).optional(),
+  criticalFields: import_zod.z.array(import_zod.z.string()).optional(),
+  significantEvents: import_zod.z.array(import_zod.z.string()).optional(),
+  tags: import_zod.z.array(import_zod.z.string()).optional()
+}).passthrough();
+var IndexDefinitionSchema = import_zod.z.object({
+  name: import_zod.z.string().optional(),
+  fields: import_zod.z.array(import_zod.z.string()).min(1),
+  substrate: import_zod.z.string().optional(),
+  unique: import_zod.z.boolean().default(false),
+  type: import_zod.z.enum(["btree", "hash", "gin", "gist", "brin"]).default("btree")
+}).passthrough();
+var ModelDefinitionSchema = import_zod.z.object({
+  name: import_zod.z.string(),
+  displayName: import_zod.z.string().optional(),
+  description: import_zod.z.string().optional(),
+  extends: import_zod.z.string().optional(),
+  mixins: import_zod.z.array(import_zod.z.string()).optional(),
+  fields: import_zod.z.record(import_zod.z.string(), FieldDefinitionSchema),
+  relationships: import_zod.z.record(import_zod.z.string(), RelationshipDefinitionSchema).optional(),
+  substrates: SubstrateRoutingSchema.optional(),
+  semantics: SemanticMetadataSchema.optional(),
+  indexes: import_zod.z.array(IndexDefinitionSchema).optional(),
+  status: import_zod.z.enum(["draft", "active", "deprecated"]).default("draft")
+}).strict();
+var ModelSchema = ModelDefinitionSchema.extend({
+  id: import_zod.z.string(),
+  version: import_zod.z.number().int(),
+  createdAt: import_core.timestampSchema,
+  updatedAt: import_core.timestampSchema,
+  entityCount: import_zod.z.number().int().optional()
+}).passthrough();
+var MigrationPlanSchema = import_zod.z.object({
+  id: import_zod.z.string(),
+  modelId: import_zod.z.string(),
+  fromVersion: import_zod.z.number().int(),
+  toVersion: import_zod.z.number().int(),
+  changes: import_zod.z.array(
+    import_zod.z.object({
+      type: import_zod.z.enum([
+        "add-field",
+        "remove-field",
+        "modify-field",
+        "add-relationship",
+        "remove-relationship"
+      ]),
+      description: import_zod.z.string(),
+      impact: import_zod.z.enum(["breaking", "non-breaking", "data-loss"]),
+      sql: import_zod.z.string().optional()
+    })
+  ),
+  riskLevel: import_zod.z.enum(["low", "medium", "high", "critical"]),
+  estimatedDowntime: import_zod.z.string().optional(),
+  rolloutStrategy: import_zod.z.enum([
+    "zero-downtime",
+    "maintenance-window",
+    "immediate"
+  ]),
+  createdAt: import_core.timestampSchema
+}).passthrough();
+var RuleDefinitionSchema = import_zod.z.object({
+  name: import_zod.z.string(),
+  description: import_zod.z.string().optional(),
+  entityTypes: import_zod.z.array(import_zod.z.string()).min(1),
+  condition: import_zod.z.string(),
+  action: import_zod.z.enum(["validate", "transform", "notify"]),
+  severity: import_zod.z.enum(["error", "warning", "info"]),
+  enabled: import_zod.z.boolean().default(true)
+}).strict();
+var MixinDefinitionSchema = import_zod.z.object({
+  name: import_zod.z.string(),
+  description: import_zod.z.string().optional(),
+  fields: import_zod.z.record(import_zod.z.string(), FieldDefinitionSchema),
+  relationships: import_zod.z.record(import_zod.z.string(), RelationshipDefinitionSchema).optional(),
+  appliesTo: import_zod.z.array(import_zod.z.string()).optional()
+}).strict();
+
+// src/service.ts
+var asPagePayload = (raw) => raw;
+var OntologyService = class {
+  constructor(http) {
+    this.http = http;
+    this.migrations = new MigrationsNamespace(this.http);
+    this.rules = new RulesNamespace(this.http);
+    this.mixins = new MixinsNamespace(this.http);
+    this.generation = new GenerationNamespace(this.http);
+  }
+  use(name) {
+    return new ModelAccessor(name, this.http);
+  }
+  list() {
+    return __async(this, arguments, function* (opts = {}) {
+      const raw = yield this.http.get("/ontology/engine/runs", opts);
+      return (0, import_core2.createPageResult)(
+        asPagePayload(raw),
+        (cursor) => this.list(__spreadProps(__spreadValues({}, opts), { cursor }))
+      );
+    });
+  }
+  create(definition) {
+    return __async(this, null, function* () {
+      const body = ModelDefinitionSchema.parse(definition);
+      return this.http.post("/ontology/engine/runs", body);
+    });
+  }
+  validate(definition) {
+    return __async(this, null, function* () {
+      const body = ModelDefinitionSchema.parse(definition);
+      return this.http.post("/ontology/engine/ontologies/validate", body);
+    });
+  }
+  checkIntegrity() {
+    return __async(this, null, function* () {
+      return this.http.get("/ontology/engine/health");
+    });
+  }
+};
+var ModelAccessor = class {
+  constructor(_name, http) {
+    this._name = _name;
+    this.http = http;
+  }
+  get(version) {
+    return __async(this, null, function* () {
+      const params = version ? { version } : void 0;
+      return this.http.get("/ontology/engine/runs", params);
+    });
+  }
+  update(definition) {
+    return __async(this, null, function* () {
+      return this.http.post("/ontology/engine/runs", definition);
+    });
+  }
+  delete(force = false) {
+    return __async(this, null, function* () {
+      return this.http.post("/ontology/engine/runs", {
+        action: "delete-model",
+        force
+      });
+    });
+  }
+  relationships() {
+    return __async(this, null, function* () {
+      return this.http.get("/ontology/engine/runs");
+    });
+  }
+  addRelationship(definition) {
+    return __async(this, null, function* () {
+      const body = RelationshipDefinitionSchema.parse(definition);
+      return this.http.post("/ontology/engine/runs", body);
+    });
+  }
+  removeRelationship(relationshipId) {
+    return __async(this, null, function* () {
+      return this.http.post("/ontology/engine/runs", {
+        action: "delete-relationship",
+        relationshipId
+      });
+    });
+  }
+  validateData() {
+    return __async(this, null, function* () {
+      return this.http.post("/ontology/engine/ontologies/validate");
+    });
+  }
+  versions() {
+    return __async(this, null, function* () {
+      return this.http.get("/ontology/engine/runs");
+    });
+  }
+};
+var MigrationsNamespace = class {
+  constructor(http) {
+    this.http = http;
+  }
+  plan(request) {
+    return __async(this, null, function* () {
+      return this.http.post(
+        "/ontology/engine/ontologies/compare-versions",
+        request
+      );
+    });
+  }
+  apply(planId, strategy = "zero-downtime") {
+    return __async(this, null, function* () {
+      return this.http.post("/ontology/engine/runs", { planId, strategy });
+    });
+  }
+  rollback(_migrationId) {
+    return __async(this, null, function* () {
+      return this.http.post("/ontology/engine/runs");
+    });
+  }
+  history() {
+    return __async(this, arguments, function* (opts = {}) {
+      const raw = yield this.http.get("/ontology/engine/runs", opts);
+      return (0, import_core2.createPageResult)(
+        asPagePayload(raw),
+        (cursor) => this.history(__spreadProps(__spreadValues({}, opts), { cursor }))
+      );
+    });
+  }
+};
+var RulesNamespace = class {
+  constructor(http) {
+    this.http = http;
+  }
+  list() {
+    return __async(this, null, function* () {
+      return this.http.get("/ontology/engine/runs");
+    });
+  }
+  create(definition) {
+    return __async(this, null, function* () {
+      const body = RuleDefinitionSchema.parse(definition);
+      return this.http.post("/ontology/engine/runs", body);
+    });
+  }
+  update(_ruleId, definition) {
+    return __async(this, null, function* () {
+      return this.http.post("/ontology/engine/runs", definition);
+    });
+  }
+  delete(ruleId) {
+    return __async(this, null, function* () {
+      return this.http.post("/ontology/engine/runs", {
+        action: "delete-rule",
+        ruleId
+      });
+    });
+  }
+  evaluate(opts) {
+    return __async(this, null, function* () {
+      return this.http.post("/ontology/engine/ontologies/validate", opts);
+    });
+  }
+};
+var MixinsNamespace = class {
+  constructor(http) {
+    this.http = http;
+  }
+  list() {
+    return __async(this, null, function* () {
+      return this.http.get("/ontology/engine/runs");
+    });
+  }
+  create(definition) {
+    return __async(this, null, function* () {
+      const body = MixinDefinitionSchema.parse(definition);
+      return this.http.post("/ontology/engine/runs", body);
+    });
+  }
+};
+var GenerationNamespace = class {
+  constructor(http) {
+    this.http = http;
+  }
+  generate(description, opts) {
+    return __async(this, null, function* () {
+      return this.http.post("/ontology/engine/ontologies/generate", __spreadValues({
+        description
+      }, opts));
+    });
+  }
+  infer(opts) {
+    return __async(this, null, function* () {
+      return this.http.post("/ontology/engine/ontologies/infer-classes", opts);
+    });
+  }
+  suggestions() {
+    return __async(this, arguments, function* (opts = {}) {
+      return this.http.get("/ontology/engine/runs", opts);
+    });
+  }
+  acceptSuggestion(_suggestionId) {
+    return __async(this, null, function* () {
+      return this.http.post("/ontology/engine/runs");
+    });
+  }
+  rejectSuggestion(_suggestionId, reason) {
+    return __async(this, null, function* () {
+      return this.http.post("/ontology/engine/runs", {
+        reason
+      });
+    });
+  }
+};
+
+// src/index.ts
+function createOntologyClient(clientOrConfig) {
+  var _a, _b, _c, _d, _e;
+  if (clientOrConfig instanceof import_core3.FrontalClient) {
+    return new OntologyService(clientOrConfig._http);
+  }
+  const http = new import_core3.HttpClient({
+    apiKey: clientOrConfig.apiKey,
+    baseUrl: (_c = (_b = (_a = clientOrConfig.baseUrl) != null ? _a : process.env.FRONTAL_ONTOLOGY_API_URL) != null ? _b : process.env.FRONTAL_API_URL) != null ? _c : "https://api.frontal.dev/v1",
+    timeout: (_d = clientOrConfig.timeout) != null ? _d : 3e4,
+    maxRetries: (_e = clientOrConfig.maxRetries) != null ? _e : 3,
+    retryDelay: 1e3,
+    headers: {},
+    environment: "production",
+    debug: false
+  });
+  return new OntologyService(http);
+}
+var ontology = new OntologyService((0, import_core3.getDefaultClient)()._http);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FieldDefinitionSchema,
+  FieldTypeSchema,
+  IndexDefinitionSchema,
+  MigrationPlanSchema,
+  MixinDefinitionSchema,
+  ModelDefinitionSchema,
+  ModelSchema,
+  OntologyService,
+  RelationshipDefinitionSchema,
+  RelationshipTypeSchema,
+  RuleDefinitionSchema,
+  SemanticMetadataSchema,
+  SubstrateRoutingSchema,
+  createOntologyClient,
+  ontology
+});