@loxtep/sdk 0.7.22 → 0.7.24

package/schemas/entity-json-schemas/connector.json

@@ -0,0 +1,188 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://loxtep.io/schemas/entity/connector.json",
+  "title": "Connector Entity",
+  "description": "JSON Schema for Connector entity in customer workspace. Connectors define reusable integration templates (e.g., Shopify, Stripe, HubSpot).",
+  "type": "object",
+  "required": [
+    "connector_id",
+    "organization_id",
+    "connector_type",
+    "name",
+    "description",
+    "category",
+    "auth_type",
+    "version",
+    "created_at",
+    "updated_at"
+  ],
+  "properties": {
+    "connector_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Unique identifier for the connector"
+    },
+    "organization_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Organization that owns this connector definition"
+    },
+    "connector_type": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 100,
+      "pattern": "^[a-z0-9-_]+$",
+      "description": "Connector type identifier (e.g., 'shopify', 'stripe', 'hubspot')"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "Display name for the connector"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 1000,
+      "description": "Connector description"
+    },
+    "category": {
+      "type": "string",
+      "enum": [
+        "e_commerce",
+        "crm",
+        "marketing",
+        "finance",
+        "database",
+        "file_storage",
+        "analytics",
+        "communication",
+        "productivity",
+        "custom"
+      ],
+      "description": "Connector category"
+    },
+    "icon_url": {
+      "type": ["string", "null"],
+      "format": "uri",
+      "description": "URL to connector icon"
+    },
+    "documentation_url": {
+      "type": ["string", "null"],
+      "format": "uri",
+      "description": "URL to connector documentation"
+    },
+    "auth_type": {
+      "type": "string",
+      "enum": ["oauth2", "api_key", "basic", "bearer", "custom", "none"],
+      "description": "Authentication type required for this connector"
+    },
+    "oauth_config": {
+      "type": ["object", "null"],
+      "description": "OAuth2 configuration (required if auth_type is oauth2)",
+      "properties": {
+        "authorization_url": {
+          "type": "string",
+          "format": "uri"
+        },
+        "token_url": {
+          "type": "string",
+          "format": "uri"
+        },
+        "scopes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 0
+        },
+        "response_type": {
+          "type": ["string", "null"]
+        },
+        "grant_type": {
+          "type": ["string", "null"]
+        },
+        "additional_params": {
+          "type": ["object", "null"],
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "supported_directions": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["inbound", "outbound", "bidirectional"]
+      },
+      "minItems": 1,
+      "description": "Data sync directions supported by this connector"
+    },
+    "supported_entities": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "minItems": 0,
+      "description": "Entity types supported by this connector (e.g., ['orders', 'customers', 'products'])"
+    },
+    "supports_webhooks": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether this connector supports webhook-based sync"
+    },
+    "supports_polling": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether this connector supports polling-based sync"
+    },
+    "required_scopes": {
+      "type": ["array", "null"],
+      "items": {
+        "type": "string"
+      },
+      "description": "OAuth scopes required for this connector"
+    },
+    "required_permissions": {
+      "type": ["array", "null"],
+      "items": {
+        "type": "string"
+      },
+      "description": "Permissions required for this connector"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Connector version (semantic versioning)"
+    },
+    "is_beta": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether this connector is in beta"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "default": {},
+      "description": "Additional metadata for the connector"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when connector was created"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when connector was last updated"
+    },
+    "deleted_at": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when connector was deleted (soft delete)"
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/entity-json-schemas/container.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://loxtep.io/schemas/entity/container.json",
+  "title": "Container Entity",
+  "description": "JSON Schema for Container entity in customer workspace. A container represents one logical node that maps to one or more bots/queues at runtime. It wraps another project entity (connection, transformation, validation, data-product, export).",
+  "type": "object",
+  "required": [
+    "container_id",
+    "organization_id",
+    "project_id",
+    "workflow_id",
+    "wrapped_entity_type",
+    "wrapped_entity_id"
+  ],
+  "properties": {
+    "container_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "Unique identifier for the container (e.g. conn-a1b2c3d4, xfm-e5f6g7h8)"
+    },
+    "organization_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Organization that owns this container"
+    },
+    "project_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Project that contains this container"
+    },
+    "workflow_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Workflow this container belongs to"
+    },
+    "wrapped_entity_type": {
+      "type": "string",
+      "enum": [
+        "connections",
+        "transformations",
+        "validations",
+        "data-products",
+        "exports",
+        "workflows"
+      ],
+      "description": "Entity type of the wrapped project entity"
+    },
+    "wrapped_entity_id": {
+      "type": "string",
+      "description": "Entity ID of the wrapped project entity (e.g. connection_id, transformation_id)"
+    },
+    "runtime": {
+      "type": "object",
+      "description": "Optional runtime slice written at deploy time; when present, project is self-describing",
+      "properties": {
+        "bot_ids": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "rstreams bot IDs registered for this container"
+        },
+        "queue_ids": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "rstreams queue names for this container"
+        }
+      }
+    }
+  }
+}

package/schemas/entity-json-schemas/contract.json

@@ -0,0 +1,228 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://loxtep.io/schemas/entity/contract.json",
+  "title": "Contract Entity",
+  "description": "JSON Schema for Contract entity in customer workspace. Contracts are versioned agreements that define guarantees (SLA/SLO) for a Data Product.",
+  "type": "object",
+  "required": [
+    "contract_id",
+    "organization_id",
+    "data_product_id",
+    "name",
+    "version",
+    "status",
+    "created_at",
+    "updated_at"
+  ],
+  "properties": {
+    "contract_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Unique identifier for the contract"
+    },
+    "organization_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Organization that owns this contract"
+    },
+    "data_product_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Reference to the data product this contract applies to"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "Contract name"
+    },
+    "description": {
+      "type": ["string", "null"],
+      "maxLength": 2000,
+      "description": "Contract description"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Contract version (semantic versioning, e.g., 1.0.0)"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "proposed", "active", "deprecated", "violated"],
+      "description": "Contract status"
+    },
+    "schema_ref": {
+      "type": ["object", "null"],
+      "description": "Reference to the schema version this contract applies to",
+      "properties": {
+        "schema_version_id": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "version": {
+          "type": "string"
+        },
+        "format": {
+          "type": "string",
+          "enum": ["json-schema", "avro", "protobuf", "custom"]
+        }
+      },
+      "additionalProperties": false
+    },
+    "guarantees": {
+      "type": "object",
+      "properties": {
+        "availability": {
+          "type": ["string", "null"],
+          "description": "Availability guarantee (e.g., '99.9%')"
+        },
+        "freshness": {
+          "type": ["string", "null"],
+          "description": "Freshness guarantee (e.g., '< 5 minutes')"
+        },
+        "completeness": {
+          "type": ["string", "null"],
+          "description": "Completeness guarantee (e.g., '99%')"
+        },
+        "accuracy": {
+          "type": ["string", "null"],
+          "description": "Accuracy guarantee (e.g., '99.5%')"
+        }
+      },
+      "additionalProperties": false,
+      "default": {}
+    },
+    "sla_definitions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["metric_type", "target_value"],
+        "properties": {
+          "metric_type": {
+            "type": "string",
+            "enum": [
+              "availability",
+              "freshness",
+              "completeness",
+              "accuracy",
+              "response_time",
+              "throughput"
+            ]
+          },
+          "target_value": {
+            "type": "number"
+          },
+          "unit": {
+            "type": ["string", "null"]
+          },
+          "measurement_window": {
+            "type": ["string", "null"]
+          },
+          "description": {
+            "type": ["string", "null"]
+          }
+        },
+        "additionalProperties": false
+      },
+      "default": [],
+      "description": "Detailed SLA definitions"
+    },
+    "sla": {
+      "type": "object",
+      "properties": {
+        "response_time": {
+          "type": ["string", "null"],
+          "description": "Response time SLA (e.g., '< 100ms p95')"
+        },
+        "throughput": {
+          "type": ["string", "null"],
+          "description": "Throughput SLA (e.g., '10000 events/sec')"
+        },
+        "support_level": {
+          "type": ["string", "null"],
+          "description": "Support level (e.g., '24x7', 'business_hours')"
+        },
+        "escalation_contact": {
+          "type": ["string", "null"],
+          "format": "email"
+        }
+      },
+      "additionalProperties": false,
+      "default": {}
+    },
+    "terms": {
+      "type": ["object", "null"],
+      "properties": {
+        "data_retention_days": {
+          "type": ["integer", "null"],
+          "minimum": 1
+        },
+        "usage_restrictions": {
+          "type": ["array", "null"],
+          "items": {
+            "type": "string"
+          }
+        },
+        "compliance_requirements": {
+          "type": ["array", "null"],
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "effective_date": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when contract becomes effective"
+    },
+    "expiration_date": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when contract expires"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "default": {},
+      "description": "Additional metadata for the contract"
+    },
+    "created_by": {
+      "type": ["string", "null"],
+      "format": "uuid",
+      "description": "User ID who created the contract"
+    },
+    "updated_by": {
+      "type": ["string", "null"],
+      "format": "uuid",
+      "description": "User ID who last updated the contract"
+    },
+    "approved_by": {
+      "type": ["string", "null"],
+      "format": "uuid",
+      "description": "User ID who approved the contract"
+    },
+    "approved_at": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when contract was approved"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when contract was created"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when contract was last updated"
+    },
+    "deleted_at": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when contract was deleted (soft delete)"
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/entity-json-schemas/data-product.json

@@ -0,0 +1,163 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://loxtep.io/schemas/entity/data-product.json",
+  "title": "Data Product Entity",
+  "description": "JSON Schema for Data Product entity in customer workspace (Studio / S3 graph). Flow-graph fields (workflow_id, upstream_entity_id, etc.) describe placement in the workflow canvas. The canonical interoperable catalog and API representation is ODPS v4.1 (Open Data Products Standard): include `odps_document` aligned with https://opendataproducts.org/v4.1/schema/odps.json — see `odps-product.json` and .kiro/specs/odps-data-product-standard in the Loxtep repo.",
+  "type": "object",
+  "required": [
+    "data_product_id",
+    "organization_id",
+    "workflow_id",
+    "name",
+    "status",
+    "created_at",
+    "updated_at"
+  ],
+  "properties": {
+    "data_product_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Unique identifier for the data product"
+    },
+    "organization_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Organization that owns this data product"
+    },
+    "workflow_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Reference to the workflow that produces this data product"
+    },
+    "domain_id": {
+      "type": ["string", "null"],
+      "format": "uuid",
+      "description": "Optional reference to the domain this data product belongs to"
+    },
+    "upstream_entity_id": {
+      "type": ["string", "null"],
+      "format": "uuid",
+      "description": "Reference to the upstream entity in the flow graph (last transformation, validation, or connection before this data product; source data product in an enrichment flow)"
+    },
+    "upstream_entity_type": {
+      "type": ["string", "null"],
+      "enum": [
+        "connections",
+        "transformations",
+        "validations",
+        "data-products",
+        null
+      ],
+      "description": "Entity type of the upstream entity"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "Data product name"
+    },
+    "description": {
+      "type": ["string", "null"],
+      "maxLength": 2000,
+      "description": "Data product description"
+    },
+    "owner": {
+      "type": "object",
+      "required": ["user_id"],
+      "properties": {
+        "user_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "User ID of the data product owner"
+        },
+        "team": {
+          "type": ["string", "null"],
+          "description": "Team name (optional)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "active", "deprecated", "archived"],
+      "description": "Data product status"
+    },
+    "governance": {
+      "type": "object",
+      "required": ["classification"],
+      "properties": {
+        "classification": {
+          "type": "string",
+          "enum": ["public", "internal", "confidential", "restricted"]
+        },
+        "pii_fields": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        },
+        "compliance_requirements": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["GDPR", "CCPA", "HIPAA", "SOX", "PCI_DSS"]
+          },
+          "default": []
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        }
+      },
+      "additionalProperties": false,
+      "default": {
+        "classification": "internal",
+        "pii_fields": [],
+        "compliance_requirements": [],
+        "tags": []
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "default": {},
+      "description": "Additional metadata for the data product"
+    },
+    "created_by": {
+      "type": ["string", "null"],
+      "format": "uuid",
+      "description": "User ID who created the data product"
+    },
+    "updated_by": {
+      "type": ["string", "null"],
+      "format": "uuid",
+      "description": "User ID who last updated the data product"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when data product was created"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when data product was last updated"
+    },
+    "deleted_at": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when data product was deleted (soft delete)"
+    },
+    "odps_document": {
+      "description": "Canonical ODPS v4.1 document (`{ product: ... }`). Preferred for platform catalog, governance, and ecosystem interoperability. Validated in the dataproducts API; Loxtep-specific fields under product.custom.loxtep.",
+      "allOf": [
+        { "$ref": "https://loxtep.io/schemas/entity/odps-product.json" }
+      ]
+    }
+  },
+  "additionalProperties": false
+}