@synity/bitrix-skills 1.3.0

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@synity/bitrix-skills",
+  "version": "1.3.0",
+  "description": "Multi-feature Bitrix24 tooling CLI for Synity projects",
+  "type": "module",
+  "bin": {
+    "bitrix-skills": "bin/bitrix-skills.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src/features",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/synity-tech/bitrix-tools.git"
+  },
+  "homepage": "https://github.com/synity-tech/bitrix-tools",
+  "bugs": {
+    "url": "https://github.com/synity-tech/bitrix-tools/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "prebuild": "node scripts/prebuild-bash-sync.mjs && node scripts/sync-assets.mjs",
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "prepublishOnly": "pnpm build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "release": "pnpm build && changeset publish",
+    "version": "changeset version",
+    "changeset": "changeset"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "bitrix24",
+    "bitrix",
+    "task-sync",
+    "claude-code",
+    "ai-tools",
+    "hooks",
+    "synity"
+  ],
+  "author": "Synity Vietnam JSC <tech@synity.vn>",
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/checkbox": "^5.1.5",
+    "@inquirer/confirm": "^6.0.13",
+    "chalk": "^5.6.2",
+    "clipanion": "4.0.0-rc.4",
+    "deepmerge": "^4.3.1",
+    "execa": "^9.0.0",
+    "kleur": "^4.1.5"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.0",
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.0"
+  }
+}

package/src/features/bx/assets/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: bx
+description: "Bitrix24 hub — type /bx to discover all Bitrix24 skills. Routes to bx:crm (contacts/deals), bx:task (project tasks), bx:calendar (events/meetings)."
+argument-hint: "[crm|task|calendar]"
+version: "1.0.0"
+---
+
+# /bx — Bitrix24 Skill Hub
+
+Detect intent → invoke the right subskill directly.
+
+| User intent | Invoke |
+|-------------|--------|
+| contact, deal, company, lead, phân tích KH, báo giá, invoice, pipeline report | `/bx:crm` |
+| task, time-log, KB summary, sync session to Bitrix, init TASK_ID | `/bx:task` |
+| meeting, lịch, calendar, nhắc nhở, schedule, kiểm tra lịch trống | `/bx:calendar` |
+
+> **Tip:** If you already know the domain, invoke the subskill directly — faster than routing through `/bx`.
+
+---
+
+## If intent is ambiguous
+
+Ask: **"CRM, task management, or calendar?"** then invoke the correct subskill.
+
+---
+
+## Subskill Quick Reference
+
+| Skill | Version | Coverage |
+|-------|---------|---------|
+| `bx:crm` | v2.0.0 | contact/company/deal/lead, analysis, reports, commerce |
+| `bx:task` | v1.1.0 | task CRUD, time-log, KB summary, session sync |
+| `bx:calendar` | v1.0.0 | events, meetings, reminders, availability, CRM sync |

package/src/features/bx/feature.json

@@ -0,0 +1,8 @@
+{
+  "name": "bx",
+  "displayName": "Bitrix Hub Skill",
+  "version": "1.0.0",
+  "target": "global",
+  "description": "Claude Code hub skill — routes to bx:crm, bx:task, bx:calendar. Install for discovery UX.",
+  "requires": {}
+}

package/src/features/bx-calendar/assets/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: bx:calendar
+description: "Synity Bitrix24 Calendar via REST API. Use for: creating meetings, scheduling events, follow-up reminders, checking team availability, syncing CRM activities to calendar. NOT for CRM records (use bx:crm) or project tasks (use bx:task)."
+argument-hint: "<subcommand> [args...]"
+version: "1.0.0"
+---
+
+# /bx:calendar — Bitrix24 Calendar Operations (Synity)
+
+**Tool**: Bitrix24 REST API via `BITRIX_WEBHOOK_URL` — no MCP Synity helpers for calendar.
+
+> ⛔ `bx:crm` = CRM entities (contact/deal). NOT for calendar events.  
+> ⛔ `bx:task` = project task management. NOT for calendar events.  
+> ✅ All calendar events, meetings, reminders, scheduling → this skill.
+
+---
+
+## Pre-flight (mandatory)
+
+```bash
+# Required env var
+echo $BITRIX_WEBHOOK_URL  # must be set: https://<portal>.bitrix24.com/rest/<user>/<token>/
+
+# Required tools
+which jq curl
+```
+
+---
+
+## Detect Intent → Load File
+
+| User intent | Load file |
+|-------------|-----------|
+| Create meeting, schedule event, link to CRM contact/deal | `meeting.md` |
+| Set reminder, follow-up after meeting | `reminder.md` |
+| Check availability, find free time slot | `availability.md` |
+| Sync CRM activity to calendar event | `sync.md` |
+
+---
+
+## Mandatory Workflow
+
+```
+1. Detect intent → load the correct subfile above
+2. Follow SOP in that file (timezone, CRM binding)
+3. Execute via REST API (curl + jq)
+4. Verify result
+```
+
+---
+
+## REST API Basics
+
+**Input parameters**: camelCase (`name`, `ownerId`, `from`, `to`)  
+**Response fields**: UPPER_SNAKE_CASE (`TZ_FROM`, `TZ_TO`, `ID`)
+
+```bash
+# Generic REST call pattern
+curl -s "${BITRIX_WEBHOOK_URL}calendar.event.add" \
+  -d "$(jq -n '{fields: {name: "...", ...}}')" | jq .
+```

package/src/features/bx-calendar/assets/availability.md

@@ -0,0 +1,65 @@
+# bx:calendar — Availability (Find Free Slots)
+
+---
+
+## Query Events for a User
+
+```bash
+# Get all events for user 1 in a date range
+curl -s "${BITRIX_WEBHOOK_URL}calendar.event.getlist" \
+  -d "$(jq -n '{
+    type: "user",
+    ownerId: 1,
+    from: "2026-05-16",
+    to: "2026-05-16"
+  }')" | jq '[.result[] | {id:.ID, name:.NAME, from:.DATE_FROM, to:.DATE_TO}]'
+```
+
+**Parameters:**
+| Parameter | Value |
+|-----------|-------|
+| `type` | `"user"` for personal calendar |
+| `ownerId` | Bitrix24 user ID |
+| `from` | Date string `"YYYY-MM-DD"` |
+| `to` | Date string `"YYYY-MM-DD"` |
+
+---
+
+## Free Slot Algorithm
+
+1. Fetch busy events for each attendee in the target date range
+2. Normalize all event times to VN timezone (`Asia/Ho_Chi_Minh`, UTC+7)
+3. Merge busy intervals per attendee → find gaps ≥ `meetingDuration`
+4. Intersect free gaps across all attendees
+5. Filter to working hours: **08:00–17:30 VN** (configurable)
+
+**Output format:**
+```
+Free slots for [date]:
+- 08:00–10:00 (2h)
+- 13:00–15:30 (2.5h)
+- 16:00–17:30 (1.5h)
+```
+
+---
+
+## Multi-User Availability Check
+
+```bash
+# Check availability for users 1, 2, 3
+for USER_ID in 1 2 3; do
+  echo "=== User $USER_ID ==="
+  curl -s "${BITRIX_WEBHOOK_URL}calendar.event.getlist" \
+    -d "$(jq -n --argjson uid $USER_ID '{type:"user", ownerId:$uid, from:"2026-05-16", to:"2026-05-16"}')" \
+    | jq '[.result[] | {from:.DATE_FROM, to:.DATE_TO, name:.NAME}]'
+done
+```
+
+---
+
+## Notes
+
+- Working hours assumption: 08:00–17:30 VN — adjust if user has different hours
+- `calendar.event.getlist` returns events where the querying user has read access
+- Response `DATE_FROM` / `DATE_TO` are in UPPER_SNAKE_CASE
+- All-day events: `DATE_FROM` has no time component — treat as blocking 00:00–23:59

package/src/features/bx-calendar/assets/meeting.md

@@ -0,0 +1,87 @@
+# bx:calendar — Meeting (Create Event + CRM Binding)
+
+---
+
+## Required Fields for calendar.event.add
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| `name` | string | Event title |
+| `type` | string | `"user"` (personal) / `"group"` (team) / `"company_calendar"` |
+| `ownerId` | number | User ID (for `type=user`) or group ID |
+| `from` | string | ISO 8601: `"2026-05-15T10:00:00+07:00"` |
+| `to` | string | ISO 8601: `"2026-05-15T11:00:00+07:00"` |
+| `section` | number | Section ID from `calendar.section.getlist` |
+| `timezone_from` | string | **Always `"Asia/Ho_Chi_Minh"` for VN meetings** |
+| `timezone_to` | string | **Always `"Asia/Ho_Chi_Minh"` for VN meetings** |
+
+---
+
+## Timezone SOP (CRITICAL)
+
+**Always set `timezone_from` and `timezone_to` = `"Asia/Ho_Chi_Minh"`** for VN meetings.
+
+Omitting timezone → server stores UTC → all VN participants see wrong time.
+
+Use ISO 8601 with offset in datetime strings:
+```
+"2026-05-15T10:00:00+07:00"   ✅ correct
+"2026-05-15T03:00:00Z"        ❌ confusing — use +07:00 explicitly
+"2026-05-15 10:00:00"         ❌ no timezone info
+```
+
+---
+
+## CRM Binding
+
+Link the event to a CRM entity via `UF_CRM_CAL_EVENT`:
+
+| Entity | Prefix format |
+|--------|--------------|
+| Deal | `D_<dealId>` → e.g. `"D_42"` |
+| Contact | `CO_<contactId>` → e.g. `"CO_15"` |
+| Company | `C_<companyId>` → e.g. `"C_7"` |
+
+```bash
+# Example: meeting linked to deal 42 + contact 15
+curl -s "${BITRIX_WEBHOOK_URL}calendar.event.add" \
+  -d "$(jq -n '{
+    name: "Demo call with Nguyen Van A",
+    type: "user",
+    ownerId: 1,
+    from: "2026-05-16T10:00:00+07:00",
+    to: "2026-05-16T11:00:00+07:00",
+    section: 3,
+    timezone_from: "Asia/Ho_Chi_Minh",
+    timezone_to: "Asia/Ho_Chi_Minh",
+    UF_CRM_CAL_EVENT: ["D_42", "CO_15"]
+  }')" | jq '.result'
+```
+
+---
+
+## Get Section ID
+
+```bash
+curl -s "${BITRIX_WEBHOOK_URL}calendar.section.getlist" \
+  -d '{"type":"user","ownerId":1}' | jq '[.result[] | {id:.ID, name:.NAME}]'
+```
+
+---
+
+## Verify Checklist
+
+- [ ] Event `ID` returned (not null)
+- [ ] Response `TZ_FROM` = `"Asia/Ho_Chi_Minh"`
+- [ ] `UF_CRM_CAL_EVENT` contains expected entity IDs
+- [ ] `from` / `to` datetimes correct
+
+---
+
+## Common Mistakes
+
+| Mistake | Result | Fix |
+|---------|--------|-----|
+| Omit `timezone_from`/`timezone_to` | Server timezone (UTC) stored | Always set both |
+| Wrong CRM prefix (`DEAL_42` instead of `D_42`) | Binding silently ignored | Use exact prefixes above |
+| Missing `section` field | API error | Fetch section ID first |

package/src/features/bx-calendar/assets/reminder.md

@@ -0,0 +1,71 @@
+# bx:calendar — Reminder (Follow-up + Pre-meeting)
+
+---
+
+## Two Reminder Use Cases
+
+### Use Case 1 — Pre-meeting notification
+
+Add `remind` array to event creation:
+
+```bash
+curl -s "${BITRIX_WEBHOOK_URL}calendar.event.add" \
+  -d "$(jq -n '{
+    name: "Demo call",
+    type: "user",
+    ownerId: 1,
+    from: "2026-05-16T10:00:00+07:00",
+    to: "2026-05-16T11:00:00+07:00",
+    section: 3,
+    timezone_from: "Asia/Ho_Chi_Minh",
+    timezone_to: "Asia/Ho_Chi_Minh",
+    remind: [{type: "min", count: 15}]
+  }')" | jq '.result'
+```
+
+**`remind` type values**: `"min"` | `"hour"` | `"day"`
+
+**Standard offsets:**
+- Pre-meeting: `{type: "min", count: 15}` (15 min before)
+- Long event: `{type: "hour", count: 1}` (1 hour before)
+
+---
+
+### Use Case 2 — Post-meeting follow-up
+
+Create a **new event** scheduled `+1 business day` after meeting end.
+
+**Business day calculation rule:**
+- If meeting ends Mon–Thu → follow-up = next day at 09:00
+- If meeting ends Fri → follow-up = Monday at 09:00
+- If meeting ends Sat/Sun → follow-up = Monday at 09:00
+- VN public holidays: out of scope (skip manually if needed)
+
+```bash
+# Follow-up event after meeting with deal 42
+FOLLOW_UP_DATE="2026-05-17T09:00:00+07:00"  # calculated +1 biz day
+FOLLOW_UP_END="2026-05-17T09:30:00+07:00"
+
+curl -s "${BITRIX_WEBHOOK_URL}calendar.event.add" \
+  -d "$(jq -n --arg d "$FOLLOW_UP_DATE" --arg e "$FOLLOW_UP_END" '{
+    name: "Follow-up: Demo call with Nguyen Van A",
+    type: "user",
+    ownerId: 1,
+    from: $d,
+    to: $e,
+    section: 3,
+    timezone_from: "Asia/Ho_Chi_Minh",
+    timezone_to: "Asia/Ho_Chi_Minh",
+    UF_CRM_CAL_EVENT: ["D_42"],
+    remind: [{type: "min", count: 30}]
+  }')" | jq '.result'
+```
+
+---
+
+## Verify Checklist
+
+- [ ] Event `ID` returned
+- [ ] For pre-meeting: `remind` array present in event details
+- [ ] For follow-up: datetime is a business day at 09:00 VN time
+- [ ] CRM deal/contact linked via `UF_CRM_CAL_EVENT`

package/src/features/bx-calendar/assets/sync.md

@@ -0,0 +1,70 @@
+# bx:calendar — Sync (CRM Activity → Calendar Event)
+
+---
+
+## Direction
+
+**One-way only: CRM Activity → Calendar Event.**
+
+No native Bitrix24 webhook for 2-way sync. After creation:
+- Editing the calendar event does NOT update the CRM activity
+- Editing the CRM activity does NOT update the calendar event
+- Manual update required if either changes after sync
+
+---
+
+## Field Mapping
+
+| CRM Activity field | Calendar event parameter | Notes |
+|-------------------|-------------------------|-------|
+| `SUBJECT` | `name` | Event title |
+| `START_TIME` | `from` | ISO 8601 + `+07:00` offset |
+| `END_TIME` | `to` | ISO 8601 + `+07:00` offset |
+| `DESCRIPTION` | `description` | Optional |
+| `OWNER_TYPE_ID` + `OWNER_ID` | `UF_CRM_CAL_EVENT` | e.g. deal → `["D_42"]` |
+| `RESPONSIBLE_ID` | `ownerId` | Bitrix24 user ID |
+
+---
+
+## Sync Steps
+
+**Step 1 — Read CRM activity**
+```bash
+curl -s "${BITRIX_WEBHOOK_URL}crm.activity.get" \
+  -d '{"id": 789}' | jq '.result | {subject:.SUBJECT, start:.START_TIME, end:.END_TIME, owner_type:.OWNER_TYPE_ID, owner_id:.OWNER_ID}'
+```
+
+**Step 2 — Map owner to CRM entity prefix**
+
+| `OWNER_TYPE_ID` | Prefix |
+|----------------|--------|
+| 2 | `CO_` (contact) |
+| 3 | `C_` (company) |
+| 4 | `D_` (deal) |
+
+**Step 3 — Create calendar event**
+```bash
+curl -s "${BITRIX_WEBHOOK_URL}calendar.event.add" \
+  -d "$(jq -n '{
+    name: "Meeting: <SUBJECT>",
+    type: "user",
+    ownerId: <RESPONSIBLE_ID>,
+    from: "<START_TIME_ISO+07:00>",
+    to: "<END_TIME_ISO+07:00>",
+    section: 3,
+    timezone_from: "Asia/Ho_Chi_Minh",
+    timezone_to: "Asia/Ho_Chi_Minh",
+    UF_CRM_CAL_EVENT: ["D_<OWNER_ID>"]
+  }')" | jq '.result'
+```
+
+**Step 4 — Verify**
+- [ ] Calendar event `ID` returned
+- [ ] `UF_CRM_CAL_EVENT` contains correct CRM entity
+- [ ] `TZ_FROM` = `"Asia/Ho_Chi_Minh"` in response
+
+---
+
+## Limitation Note
+
+> **After sync:** if you edit the calendar event or the CRM activity, the other side will NOT be updated automatically. This is a Bitrix24 platform limitation — no native 2-way sync via REST API. To update both, edit both manually.

package/src/features/bx-calendar/feature.json

@@ -0,0 +1,10 @@
+{
+  "name": "bx-calendar",
+  "displayName": "Bitrix Calendar Skill",
+  "version": "1.0.0",
+  "target": "global",
+  "description": "Claude Code skill for Bitrix24 Calendar: meetings, reminders, team availability, CRM activity sync",
+  "requires": {
+    "env": ["BITRIX_WEBHOOK_URL"]
+  }
+}

package/src/features/bx-crm/assets/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: bx:crm
+description: "Synity Bitrix24 CRM via MCP Synity. Use for: contacts, companies, deals, leads, estimates, invoices, customer analysis, pipeline reports. NOT for project tasks (use bx:task) or calendar events (use bx:calendar)."
+argument-hint: "<operation> [args]"
+version: "2.0.0"
+---
+
+# /bx:crm — Bitrix24 CRM via MCP Synity
+
+**Tool**: MCP Synity at `b24-mcp.synity.so` — entry point is `codemode.search()` → `execute`.
+
+> ⛔ `bx:task` = project task management. NOT for CRM entities.  
+> ⛔ `bx:calendar` = calendar events + meetings. NOT for CRM entities.  
+> ✅ All CRM (contact/company/deal/lead/estimate/invoice) → this skill.
+
+---
+
+## Detect Workflow → Load File
+
+| User intent | Load file | Key helpers |
+|-------------|-----------|-------------|
+| create/update contact, company, deal, lead | `onboard.md` | upsertContact, upsertCompanyByTaxCode, createDealWithParties |
+| analyze customer, signals, before meeting | `research.md` | customer360, contactSignals, dealSignals, customerJourney |
+| pipeline report, forecast, AR, overdue | `report.md` | dealForecast, stuckInStage, arReport |
+| estimate, báo giá, invoice, approve | `commerce.md` | createEstimate, approveEstimate, createSmartInvoice |
+
+If intent spans multiple workflows → load `onboard.md` first, then load others as needed.
+
+---
+
+## Mandatory Workflow
+
+```
+1. Detect intent → load the correct subfile above
+2. Follow SOP rules / output protocol in that file
+3. codemode.search() to confirm helper schema
+4. Execute via the correct helper
+5. Verify result against checklist in the subfile
+```
+
+Skipping steps 1 or 5 caused production bugs. Both are required.
+
+---
+
+## Discovery Reference
+
+```js
+// Primary — always use first
+codemode.search({ keywords: ["..."], entities: ["deal","contact","company"], intent: "write" })
+
+// Only if search() returns empty
+codemode.catalog()  // ~40 unranked helpers
+
+// For stage IDs / CRM type IDs
+codemode.entityIds()
+
+// Raw REST when no helper exists
+codemode.request({ method: "POST", path: "/crm.xxx", body: { ... } })
+```

package/src/features/bx-crm/assets/commerce.md

@@ -0,0 +1,96 @@
+# bx:crm — Commerce (Quote-to-Cash Flow)
+
+Covers: estimate → approve → smart invoice.
+
+---
+
+## Mandatory Flow Order
+
+**Do NOT skip or reorder these steps.**
+
+```
+1. createEstimate
+2. setEstimateProducts
+3. [Customer confirmation]
+4. approveEstimate
+5. closeEstimatesForDeal
+6. createSmartInvoice
+7. setInvoiceProducts  OR  copyDealProductsToInvoice
+```
+
+---
+
+## Step Details
+
+**Step 1 — Create estimate**
+```js
+createEstimate({ dealId, title, currency })
+// → returns estimateId
+```
+
+**Step 2 — Set products**
+```js
+// Option A: known products from catalog
+findProducts({ query: "product name" })  // → [{id, name, price}]
+setEstimateProducts({ estimateId, products: [{ id, price, quantity }] })
+
+// Option B: custom line items
+setEstimateProducts({ estimateId, products: [{ name, price, quantity }] })
+```
+
+**Step 3 — Wait for customer confirmation** (offline step, no API call)
+
+**Step 4 — Approve estimate**
+```js
+approveEstimate({ estimateId })
+```
+
+**Step 5 — Close other estimates for this deal**
+```js
+closeEstimatesForDeal({ dealId })  // closes all non-approved estimates
+```
+
+**Step 6 — Create smart invoice**
+```js
+createSmartInvoice({ dealId, contactId, companyId })
+// → returns invoiceId
+// Always pass BOTH contactId AND companyId — no payer = template broken
+```
+
+**Step 7 — Set invoice products (pick ONE method only)**
+```js
+// Method A: copy from deal (recommended when deal products are set)
+copyDealProductsToInvoice({ dealId, invoiceId })
+
+// Method B: set manually
+setInvoiceProducts({ invoiceId, products: [...] })
+```
+
+---
+
+## Verify Checklist (after invoice creation)
+
+- [ ] Invoice `STATUS = 'N'` (new/unpaid)
+- [ ] Payer: both `contactId` and `companyId` linked
+- [ ] Products list matches approved estimate
+- [ ] `OPPORTUNITY` on deal updated to match invoice total
+
+---
+
+## Common Mistakes
+
+| Mistake | Result | Fix |
+|---------|--------|-----|
+| `createSmartInvoice` before `approveEstimate` | Duplicate amounts, wrong totals | Follow step order strictly |
+| Using both `setInvoiceProducts` AND `copyDealProducts` | One overwrites the other | Pick ONE method only |
+| Missing `contactId` or `companyId` on invoice | No payer linked → document template broken | Always pass both |
+
+---
+
+## Products Discovery
+
+```js
+// Search product catalog before creating estimate
+findProducts({ query: "keyword", limit: 10 })
+// → [{ id, name, price, currency, unit }]
+```