@revos/cli 0.2.0 → 0.2.2

package/dist/templates/skills/create-cubes/references/hubspot-entities.md

@@ -0,0 +1,289 @@
+# HubSpot Entities Reference
+
+## Table naming
+
+Airbyte syncs HubSpot tables with a configurable prefix (default: `hubspot_`).
+Inspect the BigQuery dataset to identify the actual prefix:
+
+```sql
+SELECT table_name FROM `<dataset>.INFORMATION_SCHEMA.TABLES`
+WHERE table_name LIKE '%companies%' OR table_name LIKE '%deals%'
+ORDER BY table_name LIMIT 20;
+```
+
+Throughout this document `<prefix>` is a placeholder for that prefix (e.g. `hubspot_`).
+
+---
+
+## Primary entities
+
+| Cube name                | BigQuery table           | PK           | Notes                                              |
+| ------------------------ | ------------------------ | ------------ | -------------------------------------------------- | --- | --- | --- | --------- |
+| `<prefix>companies`      | `<prefix>companies`      | `id`         | `properties_name` is the display name              |
+| `<prefix>contacts`       | `<prefix>contacts`       | `id`         | `properties_hs_full_name_or_email` is display name |
+| `<prefix>deals`          | `<prefix>deals`          | `id`         | `properties_dealname` is display name              |
+| `<prefix>tickets`        | `<prefix>tickets`        | `id`         | —                                                  |
+| `<prefix>owners`         | `<prefix>owners`         | `id`         | Display name: `firstName                           |     | ' ' |     | lastName` |
+| `<prefix>engagements`    | `<prefix>engagements`    | `id`         | See engagement sub-types below                     |
+| `<prefix>deal_pipelines` | `<prefix>deal_pipelines` | `pipelineId` | Stages stored as JSON array                        |
+| `<prefix>line_items`     | `<prefix>line_items`     | `id`         | `properties_name`                                  |
+| `<prefix>products`       | `<prefix>products`       | `id`         | `properties_name`                                  |
+
+**Owner join pattern (shared by companies, contacts, deals, tickets):**
+
+```yaml
+joins:
+  <prefix>owners:
+    relationship: many_to_one
+    sql: "${CUBE}.properties_hubspot_owner_id = ${<prefix>owners.id}"
+```
+
+---
+
+## Bridge / junction cubes (public: false)
+
+HubSpot stores many-to-many associations as JSON arrays on the primary object.
+Bridge cubes are required to join across these associations. They must be
+`public: false` and use a composite PK.
+
+### Association columns
+
+| Source table          | Column                    | Contains                                |
+| --------------------- | ------------------------- | --------------------------------------- |
+| `<prefix>deals`       | `companies`               | JSON array of company IDs               |
+| `<prefix>deals`       | `contacts`                | JSON array of contact IDs               |
+| `<prefix>deals`       | `line_items`              | JSON array of line item IDs             |
+| `<prefix>deals`       | `deals`                   | JSON array (for tickets→deals)          |
+| `<prefix>tickets`     | `companies`               | JSON array of company IDs               |
+| `<prefix>tickets`     | `contacts`                | JSON array of contact IDs               |
+| `<prefix>tickets`     | `deals`                   | JSON array of deal IDs (CAST to STRING) |
+| `<prefix>companies`   | `contacts`                | JSON array of contact IDs               |
+| `<prefix>engagements` | `associations.contactIds` | JSON array of contact IDs               |
+| `<prefix>engagements` | `associations.companyIds` | JSON array of company IDs               |
+| `<prefix>engagements` | `associations.dealIds`    | JSON array of deal IDs                  |
+
+### Bridge cube: companies_to_deals
+
+```yaml
+name: <prefix>companies_to_deals
+sql: >
+  SELECT DISTINCT d.id as deal_id, company_id
+  FROM `<dataset>.<prefix>deals` d,
+  UNNEST(JSON_VALUE_ARRAY(d.companies)) company_id
+public: false
+dimensions:
+  id:
+    sql: "${CUBE.company_id} || ${CUBE.deal_id}"
+    type: string
+    primary_key: true
+  company_id:
+    sql: "${CUBE}.company_id"
+    type: string
+  deal_id:
+    sql: "${CUBE}.deal_id"
+    type: string
+joins:
+  <prefix>companies:
+    relationship: many_to_one
+    sql: "${CUBE}.company_id = ${<prefix>companies.id}"
+  <prefix>deals:
+    relationship: many_to_one
+    sql: "${CUBE}.deal_id = ${<prefix>deals.id}"
+refresh_key:
+  sql: "SELECT MAX(_airbyte_extracted_at) FROM `<dataset>.<prefix>deals`"
+```
+
+### Bridge cube: companies_to_tickets
+
+Same pattern — UNNEST `tickets.companies`:
+
+```yaml
+name: <prefix>companies_to_tickets
+sql: >
+  SELECT DISTINCT t.id as ticket_id, company_id
+  FROM `<dataset>.<prefix>tickets` t,
+  UNNEST(JSON_VALUE_ARRAY(t.companies)) company_id
+```
+
+### Bridge cube: deals_to_tickets
+
+Note: ticket `deals` column values are numbers — cast to STRING:
+
+```yaml
+name: <prefix>deals_to_tickets
+sql: >
+  SELECT DISTINCT t.id AS ticket_id, CAST(deal_id AS STRING) AS deal_id
+  FROM `<dataset>.<prefix>tickets` t,
+  UNNEST(JSON_VALUE_ARRAY(t.deals)) AS deal_id
+```
+
+### Bridge cube: deals_to_line_items
+
+```yaml
+name: <prefix>deals_to_line_items
+sql: >
+  SELECT DISTINCT d.id AS deal_id, line_item_id
+  FROM `<dataset>.<prefix>deals` d,
+  UNNEST(JSON_VALUE_ARRAY(d.line_items)) AS line_item_id
+```
+
+### Bridge cube: contacts_to_deals
+
+```yaml
+name: <prefix>contacts_to_deals
+sql: >
+  SELECT DISTINCT d.id AS deal_id, contact_id
+  FROM `<dataset>.<prefix>deals` d,
+  UNNEST(JSON_VALUE_ARRAY(d.contacts)) contact_id
+```
+
+### Bridge cube: contacts_to_tickets
+
+```yaml
+name: <prefix>contacts_to_tickets
+sql: >
+  SELECT DISTINCT t.id AS ticket_id, contact_id
+  FROM `<dataset>.<prefix>tickets` t,
+  UNNEST(JSON_VALUE_ARRAY(t.contacts)) contact_id
+```
+
+### Bridge cube: contacts_to_companies
+
+Note: this uses `SAFE_CAST` on both sides — IDs can have type mismatches:
+
+```yaml
+name: <prefix>contacts_to_companies
+sql: >
+  SELECT DISTINCT c.id AS company_id, contact_id
+  FROM `<dataset>.<prefix>companies` c,
+  UNNEST(JSON_VALUE_ARRAY(c.contacts)) AS contact_id
+joins:
+  <prefix>contacts:
+    relationship: many_to_one
+    sql: "SAFE_CAST(${CUBE}.contact_id AS STRING) = SAFE_CAST(${<prefix>contacts.id} AS STRING)"
+  <prefix>companies:
+    relationship: many_to_one
+    sql: "SAFE_CAST(${CUBE}.company_id AS STRING) = SAFE_CAST(${<prefix>companies.id} AS STRING)"
+```
+
+### Bridge cubes: engagements_to_contacts / companies / deals
+
+Engagement IDs are integers — always CAST to STRING:
+
+```yaml
+name: <prefix>engagements_to_contacts
+sql: >
+  SELECT DISTINCT
+    CAST(e.id AS STRING) AS engagement_id,
+    CAST(contact_id AS STRING) AS contact_id
+  FROM `<dataset>.<prefix>engagements` e,
+  UNNEST(JSON_VALUE_ARRAY(e.associations.contactIds)) AS contact_id
+```
+
+Same pattern for `companyIds` → `engagements_to_companies` and `dealIds` → `engagements_to_deals`.
+
+Engagement join:
+
+```yaml
+joins:
+  <prefix>engagements:
+    relationship: many_to_one
+    sql: "CAST(${CUBE}.engagement_id AS STRING) = CAST(${<prefix>engagements.id} AS STRING)"
+```
+
+---
+
+## Special cubes
+
+### deal_pipeline_stages
+
+Derived from `deal_pipelines.stages` JSON array. Not a raw table — uses `sql:` not `sql_table:`.
+
+```yaml
+name: <prefix>deal_pipeline_stages
+sql: >
+  SELECT
+    JSON_VALUE(elem, '$.stageId') AS stage_id,
+    JSON_VALUE(elem, '$.label') AS label
+  FROM `<dataset>.<prefix>deal_pipelines`,
+  UNNEST(JSON_QUERY_ARRAY(stages)) AS elem
+dimensions:
+  stage_id:
+    sql: "${CUBE}.stage_id"
+    type: string
+    primary_key: true
+  label:
+    sql: "${CUBE}.label"
+    type: string
+joins:
+  <prefix>deals:
+    relationship: one_to_many
+    sql: "${CUBE}.stage_id = ${<prefix>deals.properties_dealstage}"
+refresh_key:
+  sql: "SELECT MAX(_airbyte_extracted_at) FROM `<dataset>.<prefix>deal_pipelines`"
+```
+
+Deals join to stages and pipelines:
+
+```yaml
+joins:
+  <prefix>deal_pipeline_stages:
+    relationship: many_to_one
+    sql: "${CUBE}.properties_dealstage = ${<prefix>deal_pipeline_stages.stage_id}"
+  <prefix>deal_pipelines:
+    relationship: many_to_one
+    sql: "${CUBE}.properties_pipeline = ${<prefix>deal_pipelines.pipelineId}"
+```
+
+### engagements sub-types
+
+`engagements` table has sub-type tables: `engagements_calls`, `engagements_emails`,
+`engagements_meetings`, `engagements_tasks`, `engagements_notes`.
+
+Join pattern (one-to-one by ID with CAST):
+
+```yaml
+# On the engagements cube:
+joins:
+  <prefix>engagements_calls:
+    relationship: one_to_one
+    sql: "CAST(${CUBE}.id AS STRING) = ${<prefix>engagements_calls.id}"
+
+# On each sub-type cube:
+joins:
+  <prefix>engagements:
+    relationship: many_to_one
+    sql: "${CUBE}.id = CAST(${<prefix>engagements.id} AS STRING)"
+```
+
+---
+
+## Deals measures
+
+```yaml
+measures:
+  count_closed:
+    type: count
+    filters:
+      - sql: "${CUBE}.properties_hs_is_closed = TRUE"
+  count_closed_won:
+    type: count
+    filters:
+      - sql: "${CUBE}.properties_hs_is_closed_won = TRUE"
+  count_closed_lost:
+    type: count
+    filters:
+      - sql: >
+          ${CUBE}.properties_hs_is_closed = TRUE
+          AND ${CUBE}.properties_hs_is_closed_won = FALSE
+```
+
+---
+
+## Common pitfalls
+
+1. **ID type mismatches** — HubSpot IDs are sometimes integers, sometimes strings. Use `SAFE_CAST` when unsure (especially contacts_to_companies). Engagement IDs are always integers → always CAST to STRING.
+2. **JSON_VALUE_ARRAY vs JSON_QUERY_ARRAY** — use `JSON_VALUE_ARRAY` when the array contains scalar strings/ints (association IDs); use `JSON_QUERY_ARRAY` when the array contains JSON objects (deal_pipelines stages).
+3. **deal_pipeline_stages is derived** — uses `sql:` not `sql_table:`. Cannot be used in `revos cubes preview` diff against Airbyte-generated cubes.
+4. **engagements bridge refresh_key** — use the parent engagement table timestamp, not the contact/company/deal table.
+5. **Prefix varies** — always confirm the actual prefix from BigQuery before writing cube files.

package/dist/templates/skills/create-cubes/references/jira-entities.md

@@ -0,0 +1,201 @@
+# Jira Entities Reference
+
+## Table naming
+
+Airbyte syncs Jira tables with a configurable prefix (default: `jira_`).
+Inspect the BigQuery dataset to find the actual prefix:
+
+```sql
+SELECT table_name FROM `<dataset>.INFORMATION_SCHEMA.TABLES`
+WHERE table_name LIKE '%issues%' OR table_name LIKE '%projects%'
+ORDER BY table_name LIMIT 20;
+```
+
+Throughout this document `<prefix>` is a placeholder for that prefix.
+
+---
+
+## Primary entities
+
+| Cube name                    | BigQuery table               | PK          | Notes                                            |
+| ---------------------------- | ---------------------------- | ----------- | ------------------------------------------------ |
+| `<prefix>issues`             | `<prefix>issues`             | `id`        | `key` is display name; metadata in `fields` JSON |
+| `<prefix>projects`           | `<prefix>projects`           | `id`        | `name`                                           |
+| `<prefix>issue_types`        | `<prefix>issue_types`        | `id`        | `name`                                           |
+| `<prefix>issue_priorities`   | `<prefix>issue_priorities`   | `id`        | `name`                                           |
+| `<prefix>users`              | `<prefix>users`              | `accountId` | `displayName`; aliased 4× (see below)            |
+| `<prefix>sprints`            | `<prefix>sprints`            | `id`        | `name`; FK `boardId`                             |
+| `<prefix>boards`             | `<prefix>boards`             | `id`        | `name`; FK `projectId`                           |
+| `<prefix>issue_comments`     | `<prefix>issue_comments`     | —           | FK `issueId`; `author` is JSON object            |
+| `<prefix>issue_worklogs`     | `<prefix>issue_worklogs`     | —           | FK `issueId`; `author` is JSON object            |
+| `<prefix>project_components` | `<prefix>project_components` | —           | FK `projectId` as INT64                          |
+| `<prefix>project_versions`   | `<prefix>project_versions`   | —           | FK `projectId` as INT64                          |
+
+---
+
+## Users table aliasing
+
+The single `<prefix>users` table must be exposed as **separate cubes** for each
+role because Cube.js does not support joining the same table twice with
+different conditions. Each alias has its own cube name and `sql_table` pointing
+to the same physical table.
+
+| Cube name                      | Role           | Join condition on `<prefix>issues`                 |
+| ------------------------------ | -------------- | -------------------------------------------------- |
+| `<prefix>users_assignee`       | Assignee       | `JSON_VALUE(fields, '$.assignee.accountId')`       |
+| `<prefix>users_reporter`       | Reporter       | `JSON_VALUE(fields, '$.reporter.accountId')`       |
+| `<prefix>users_creator`        | Creator        | `JSON_VALUE(fields, '$.creator.accountId')`        |
+| `<prefix>users_comment_author` | Comment author | `JSON_VALUE(issue_comments.author, '$.accountId')` |
+| `<prefix>users_worklog_author` | Worklog author | `JSON_VALUE(issue_worklogs.author, '$.accountId')` |
+| `<prefix>users`                | Direct queries | (no joins defined)                                 |
+
+Template for each alias:
+
+```yaml
+name: <prefix>users_assignee
+sql_table: "`<dataset>.<prefix>users`"
+joins:
+  <prefix>issues:
+    relationship: one_to_many
+    sql: >
+      ${CUBE}.accountId =
+      JSON_VALUE(${<prefix>issues.fields}, '$.assignee.accountId')
+```
+
+Corresponding join on `<prefix>issues`:
+
+```yaml
+joins:
+  <prefix>users_assignee:
+    relationship: many_to_one
+    sql: >
+      JSON_VALUE(${CUBE}.fields, '$.assignee.accountId') =
+      ${<prefix>users_assignee.accountId}
+```
+
+---
+
+## Issues: fields JSON column
+
+Issue metadata lives in a single `fields` JSON column. Extract with `JSON_VALUE`:
+
+| Field               | JSON path                                 |
+| ------------------- | ----------------------------------------- |
+| Issue type ID       | `$.issuetype.id`                          |
+| Priority ID         | `$.priority.id`                           |
+| Assignee account ID | `$.assignee.accountId`                    |
+| Reporter account ID | `$.reporter.accountId`                    |
+| Creator account ID  | `$.creator.accountId`                     |
+| Status              | `$.status.name`                           |
+| Summary             | `$.summary`                               |
+| Story points        | `$.story_points` or `$.customfield_10016` |
+
+Example dimension:
+
+```yaml
+dimensions:
+  status:
+    sql: "JSON_VALUE(${CUBE}.fields, '$.status.name')"
+    type: string
+  issue_type_name:
+    sql: "JSON_VALUE(${CUBE}.fields, '$.issuetype.name')"
+    type: string
+```
+
+---
+
+## Bridge / junction cubes (public: false)
+
+### sprint_issues
+
+Sprints and issues are many-to-many. The `sprint_issues` table has columns
+`issueId` (STRING) and `sprintId` (INT64). Composite PK required.
+
+```yaml
+name: <prefix>sprint_issues
+sql_table: "`<dataset>.<prefix>sprint_issues`"
+public: false
+dimensions:
+  id:
+    sql: "${CUBE}.issueId || '_' || CAST(${CUBE}.sprintId AS STRING)"
+    type: string
+    primary_key: true
+joins:
+  <prefix>issues:
+    relationship: many_to_one
+    sql: "${CUBE}.issueId = ${<prefix>issues.id}"
+  <prefix>sprints:
+    relationship: many_to_one
+    sql: "${CUBE}.sprintId = ${<prefix>sprints.id}"
+```
+
+Issues and sprints join through this bridge:
+
+```yaml
+# On <prefix>issues:
+joins:
+  <prefix>sprint_issues:
+    relationship: one_to_many
+    sql: "${CUBE}.id = ${<prefix>sprint_issues.issueId}"
+
+# On <prefix>sprints:
+joins:
+  <prefix>sprint_issues:
+    relationship: one_to_many
+    sql: "${CUBE}.id = ${<prefix>sprint_issues.sprintId}"
+```
+
+### board_issues
+
+Board issues (`board_issues` table) link boards to issues. Composite PK uses `id` + `boardId`.
+
+```yaml
+name: <prefix>board_issues
+sql_table: "`<dataset>.<prefix>board_issues`"
+public: false
+dimensions:
+  composite_id:
+    sql: "${CUBE}.id || '_' || CAST(${CUBE}.boardId AS STRING)"
+    type: string
+    primary_key: true
+joins:
+  <prefix>issues:
+    relationship: many_to_one
+    sql: "${CUBE}.id = ${<prefix>issues.id}"
+  <prefix>boards:
+    relationship: many_to_one
+    sql: "${CUBE}.boardId = ${<prefix>boards.id}"
+```
+
+---
+
+## Type casting pitfalls
+
+### project_components / project_versions → projects
+
+`project_components.projectId` and `project_versions.projectId` are INT64 but
+`projects.id` is STRING. Always cast:
+
+```yaml
+# On <prefix>project_components:
+joins:
+  <prefix>projects:
+    relationship: many_to_one
+    sql: "CAST(${CUBE}.projectId AS STRING) = ${<prefix>projects.id}"
+
+# On <prefix>projects:
+joins:
+  <prefix>project_components:
+    relationship: one_to_many
+    sql: "SAFE_CAST(${CUBE}.id AS INT64) = ${<prefix>project_components.projectId}"
+```
+
+---
+
+## Common pitfalls
+
+1. **`fields` JSON column** — most issue attributes live here, not as top-level columns. Always check `INFORMATION_SCHEMA` before assuming a column exists at the top level.
+2. **User aliases must be separate cubes** — do not try to join `users` twice from `issues`; Cube.js requires distinct cube names per join target.
+3. **`sprintId` is INT64** — cast to STRING in the composite PK to avoid type errors.
+4. **`issue_comments.author` is a JSON object** — extract `accountId` with `JSON_VALUE`, not a direct column reference.
+5. **`boards.projectId` vs `projects.id`** — both are strings here; no cast needed. But `project_components.projectId` is INT64 — always cast.

package/dist/templates/skills/create-cubes/references/netsuite-entities.md

@@ -0,0 +1,121 @@
+# NetSuite Entities Reference
+
+## Table naming
+
+Airbyte syncs NetSuite tables with a configurable prefix (default: `netsuite_`).
+Inspect the BigQuery dataset to confirm:
+
+```sql
+SELECT table_name FROM `<dataset>.INFORMATION_SCHEMA.TABLES`
+WHERE table_name LIKE '%customer%' OR table_name LIKE '%salesorder%'
+ORDER BY table_name LIMIT 20;
+```
+
+Throughout this document `<prefix>` is a placeholder for that prefix.
+
+---
+
+## Primary entities
+
+| Cube name             | BigQuery table        | PK   | Notes                          |
+| --------------------- | --------------------- | ---- | ------------------------------ |
+| `<prefix>customer`    | `<prefix>customer`    | `id` | FK `subsidiary` is JSON object |
+| `<prefix>contact`     | `<prefix>contact`     | `id` | FK `company` is JSON object    |
+| `<prefix>opportunity` | `<prefix>opportunity` | `id` | FK `entity` is JSON object     |
+| `<prefix>salesorder`  | `<prefix>salesorder`  | `id` | FK `entity` is JSON object     |
+| `<prefix>employee`    | `<prefix>employee`    | `id` | —                              |
+
+---
+
+## FK extraction pattern
+
+NetSuite stores foreign keys as **JSON objects** with an `id` field rather than
+as flat FK columns. Use `JSON_VALUE` to extract the ID and expose it as a
+computed dimension.
+
+### contact → customer
+
+`contact.company` is a JSON object: `{"id": "123", "refName": "Acme Corp"}`.
+
+```yaml
+name: <prefix>contact
+sql_table: "`<dataset>.<prefix>contact`"
+dimensions:
+  id:
+    sql: "id"
+    type: string
+    primary_key: true
+  customer_id:
+    sql: "JSON_VALUE(${CUBE}.company, '$.id')"
+    type: string
+joins:
+  <prefix>customer:
+    relationship: many_to_one
+    sql: "${CUBE.customer_id} = ${<prefix>customer.id}"
+```
+
+### customer → subsidiary
+
+`customer.subsidiary` is a JSON object: `{"id": "1", "refName": "Main Subsidiary"}`.
+
+```yaml
+name: <prefix>customer
+sql_table: "`<dataset>.<prefix>customer`"
+dimensions:
+  subsidiary_id:
+    sql: "JSON_VALUE(${CUBE}.subsidiary, '$.id')"
+    type: string
+joins:
+  <prefix>contact:
+    relationship: one_to_many
+    sql: "${CUBE}.id = ${<prefix>contact.customer_id}"
+  <prefix>salesorder:
+    relationship: one_to_many
+    sql: "${CUBE}.id = ${<prefix>salesorder.customer_id}"
+  <prefix>opportunity:
+    relationship: one_to_many
+    sql: "${CUBE}.id = ${<prefix>opportunity.customer_id}"
+```
+
+### opportunity / salesorder → customer
+
+Both `opportunity` and `salesorder` use `entity` (not `company`) as the FK column:
+
+```yaml
+name: <prefix>opportunity
+sql_table: "`<dataset>.<prefix>opportunity`"
+dimensions:
+  id:
+    sql: "id"
+    type: string
+    primary_key: true
+  customer_id:
+    sql: "JSON_VALUE(${CUBE}.entity, '$.id')"
+    type: string
+joins:
+  <prefix>customer:
+    relationship: many_to_one
+    sql: "${CUBE.customer_id} = ${<prefix>customer.id}"
+```
+
+Same pattern for `<prefix>salesorder`.
+
+---
+
+## Relationship graph
+
+```
+customer ──< contact
+customer ──< opportunity
+customer ──< salesorder
+```
+
+---
+
+## Common pitfalls
+
+1. **FK columns are JSON objects** — `contact.company`, `opportunity.entity`, `salesorder.entity`, `customer.subsidiary` are all JSON objects. Never join directly; always extract with `JSON_VALUE(..., '$.id')` and expose as a computed dimension.
+2. **`entity` vs `company`** — contacts use `company`, but opportunities and sales orders use `entity` as the customer FK column.
+3. **PK column name is `id` (lowercase)** — not `internalId` or similar. Verify in INFORMATION_SCHEMA.
+4. **Subsidiary** — `customer.subsidiary` holds the subsidiary FK. If the schema has multiple subsidiaries, you may need a `subsidiary` cube joined via `subsidiary_id`.
+5. **No `_airbyte_extracted_at` guarantee** — some NetSuite streams use `lastModifiedDate` instead. Check actual column names before writing `refresh_key`.