@contentstack/datasync-mongodb-sdk 1.0.13 → 1.0.15

package/.cursor/rules/README.md

@@ -0,0 +1,5 @@
+# Cursor (optional)
+
+**Cursor** users: start at the repo root **[`AGENTS.md`](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`** (universal for any editor or tool).
+
+This folder **only** contains this **README** — no `.mdc` or other rule files — so nothing editor-specific duplicates the canonical docs.

package/.github/workflows/check-version-bump.yml

@@ -0,0 +1,79 @@
+# Catches when developers forget to bump package.json for release-affecting changes.
+# App code changes (app.js, bin/, config/, routes/, views/, etc.) require a version bump vs latest tag.
+# Skips for: test-only, docs, .github (workflows/config), dependency-only bumps without app edits.
+name: Check Version Bump
+
+on:
+  pull_request:
+
+jobs:
+  version-bump:
+    name: Version bump
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Detect changed files and version bump
+        id: detect
+        run: |
+          if git rev-parse HEAD^2 >/dev/null 2>&1; then
+            FILES=$(git diff --name-only HEAD^1 HEAD^2)
+          else
+            FILES=$(git diff --name-only HEAD~1 HEAD)
+          fi
+          VERSION_FILES_CHANGED=false
+          echo "$FILES" | grep -qx 'package.json' && VERSION_FILES_CHANGED=true
+          echo "version_files_changed=$VERSION_FILES_CHANGED" >> $GITHUB_OUTPUT
+          # App source paths for this boilerplate (no lib/webpack/dist); .github/ and test/ do not count
+          CODE_CHANGED=false
+          echo "$FILES" | grep -qE '^app\.js$|^bin/|^config/|^middlewares/|^models/|^public/|^routes/|^views/|^schemaNentries/' && CODE_CHANGED=true
+          echo "$FILES" | grep -qx 'package.json' && CODE_CHANGED=true
+          echo "code_changed=$CODE_CHANGED" >> $GITHUB_OUTPUT
+
+      - name: Skip when only test/docs/.github changed
+        if: steps.detect.outputs.code_changed != 'true'
+        run: |
+          echo "No release-affecting files changed (e.g. only test/docs/.github). Skipping version-bump check."
+          exit 0
+
+      - name: Fail when version bump was missed
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed != 'true'
+        run: |
+          echo "::error::This PR has code changes but no version bump. Please bump the version in package.json."
+          exit 1
+
+      - name: Setup Node
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+
+      - name: Check version bump
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed == 'true'
+        run: |
+          set -e
+          PKG_VERSION=$(node -p "require('./package.json').version.replace(/^v/, '')")
+          if [ -z "$PKG_VERSION" ]; then
+            echo "::error::Could not read version from package.json"
+            exit 1
+          fi
+          git fetch --tags --force 2>/dev/null || true
+          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || true)
+          if [ -z "$LATEST_TAG" ]; then
+            echo "No existing tags found. Skipping version-bump check (first release)."
+            exit 0
+          fi
+          LATEST_VERSION="${LATEST_TAG#v}"
+          LATEST_VERSION="${LATEST_VERSION%%-*}"
+          if [ "$(printf '%s\n' "$LATEST_VERSION" "$PKG_VERSION" | sort -V | tail -1)" != "$PKG_VERSION" ]; then
+            echo "::error::Version bump required: package.json version ($PKG_VERSION) is not greater than latest tag ($LATEST_TAG). Please bump the version in package.json."
+            exit 1
+          fi
+          if [ "$PKG_VERSION" = "$LATEST_VERSION" ]; then
+            echo "::error::Version bump required: package.json version ($PKG_VERSION) equals latest tag ($LATEST_TAG). Please bump the version in package.json."
+            exit 1
+          fi
+          echo "Version bump check passed: package.json is at $PKG_VERSION (latest tag: $LATEST_TAG)."

package/.github/workflows/release.yml

@@ -1,8 +1,8 @@
 name: Release
 
 on:
-  push:
-    branches: [master]
+  release:
+    types: [created]
 
 jobs:
   build:
@@ -43,35 +43,13 @@ jobs:
           token: ${{ secrets.NPM_TOKEN }}
           # access: public # Uncomment this line if you want to publish the package as public for first time
 
-      # Auto-tag the new version if a change is detected
-      - name: Auto-tag new version
-        id: update_tag
-        uses: Klemensas/action-autotag@stable
-        with:
-          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
-          tag_prefix: "v"
-
-      # Create a new GitHub Release
-      - name: Create GitHub Release
-        if: steps.update_tag.outputs.tagname != ''
-        uses: actions/create-release@v1
-        id: create_release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          tag_name: ${{ steps.update_tag.outputs.tagname }}
-          release_name: Release ${{ steps.update_tag.outputs.tagname }}
-          draft: false
-          prerelease: false
-
-      # Upload the packaged .tgz file as a release asset
+      # Upload the packaged .tgz to the release that triggered this workflow
       - name: Upload Release Asset
-        if: steps.update_tag.outputs.tagname != ''
         uses: actions/upload-release-asset@v1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
-          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          upload_url: ${{ github.event.release.upload_url }}
           asset_path: "./contentstack-datasync-mongodb-sdk-${{ steps.package.outputs.version }}.tgz"
           asset_name: "contentstack-datasync-mongodb-sdk-${{ steps.package.outputs.version }}.tgz"
           asset_content_type: application/tgz

package/.github/workflows/sca-scan.yml

@@ -13,3 +13,6 @@ jobs:
           SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
         with:
           args: --all-projects --fail-on=all
+          json: true
+        continue-on-error: true
+      - uses: contentstack/sca-policy@main

package/.husky/post-checkout

@@ -0,0 +1,40 @@
+#!/usr/bin/env sh
+# When switching to a branch that doesn't exist on remote (e.g. newly created),
+# pull and merge origin/main or origin/master into current branch. Does not push.
+
+# Only run on branch checkout (not file checkout)
+if [ "$3" != "1" ]; then
+  exit 0
+fi
+
+# Skip if we don't have a remote
+if ! git rev-parse --verify origin 2>/dev/null; then
+  exit 0
+fi
+
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# Skip main/master - no need to merge base into these
+case "$CURRENT_BRANCH" in
+  main|master) exit 0 ;;
+esac
+
+# Only run when current branch does not exist on origin (treat as new local branch)
+if git ls-remote --heads origin "$CURRENT_BRANCH" 2>/dev/null | grep -q .; then
+  echo "post-checkout: $CURRENT_BRANCH exists on origin, skipping merge."
+  exit 0
+fi
+
+# Prefer main, fallback to master
+if git rev-parse --verify origin/main 2>/dev/null; then
+  BASE=origin/main
+elif git rev-parse --verify origin/master 2>/dev/null; then
+  BASE=origin/master
+else
+  exit 0
+fi
+
+echo "New branch detected: merging latest $BASE into $CURRENT_BRANCH (local only, not pushing)..."
+git fetch origin
+git merge "$BASE" --no-edit --no-ff
+echo "Done. Merge is local only; push when ready."

package/AGENTS.md

@@ -0,0 +1,92 @@
+# AI agent docs — `@contentstack/datasync-mongodb-sdk`
+
+You are working on the **Contentstack DataSync MongoDB SDK** — a library that queries **MongoDB** (or a Mongo-compatible store) holding content synced via **Contentstack DataSync**, **not** the Content **Delivery** (CDA) or **Management** (CMA) HTTP SDKs. Core behavior uses the **MongoDB driver** and queries against **persisted sync data**, not live stack REST calls for normal reads.
+
+## Single source of truth
+
+| Layer | Role |
+|-------|------|
+| **[`.cursor/rules/README.md`](.cursor/rules/README.md)** | Optional Cursor pointer (the **only** file under `.cursor/rules/`); links to **`AGENTS.md`** and **`skills/`** |
+| **`AGENTS.md`** (this file) | Universal entry: identity, out-of-scope, links, tech stack, commands, skills index |
+| **`skills/<name>/SKILL.md`** | Full conventions and checklists (source of truth for depth) |
+
+**Flow:** [`.cursor/rules/README.md`](.cursor/rules/README.md) → **`AGENTS.md`** → **`skills/<name>/SKILL.md`**
+
+## Out of scope (unless comparing or documenting migration)
+
+- **Not** the CDA or CMA **HTTP** client SDKs.
+- **Not** live Contentstack **REST** reads for normal query paths — this SDK targets **synced data in MongoDB**.
+
+## Repository
+
+| | |
+|--|--|
+| **npm** | `@contentstack/datasync-mongodb-sdk` |
+| **Git** | [https://github.com/contentstack/datasync-mongodb-sdk](https://github.com/contentstack/datasync-mongodb-sdk) |
+| **Product docs** | [Contentstack DataSync](https://www.contentstack.com/docs/guide/synchronization/contentstack-datasync) |
+
+## Tech stack
+
+| Area | Details |
+|------|---------|
+| Language | TypeScript `^4.9.5` (`package.json`); `tsc` → `dist/`, declarations `typings/` (`tsconfig.json`) |
+| Runtime | Node `>=8` (`engines`); README may suggest a newer Node for local dev |
+| Build | `npm run compile` (`tsc`); `npm run build-ts` (`clean` + `tsc`) |
+| Test | Jest `^29` + ts-jest, Node env, coverage on (`jest.config.js`). **`npm test` is `jest` only** — no `pretest` in `package.json` |
+| Lint | **TSLint** — `npm run tslint` + `tslint.json` on `src/**/*.ts`. **No ESLint** / no `npm run lint` in this repo |
+| Runtime deps | `mongodb`, `lodash`, `sift` |
+| Docs | `npm run build-doc` (builds then JSDoc → `docs/`) |
+
+## Source layout and public entry points
+
+| Role | Path |
+|------|------|
+| Package entry | `dist/index.js` (`main`) |
+| Public API | `src/index.ts` — `Contentstack`, `Contentstack.Stack(config, db?)` |
+| Query / connection | `src/stack.ts` |
+| Defaults + validation | `src/config.ts`, `src/util.ts` |
+| Messages | `src/messages.ts` |
+| Tests + fixtures | `test/`, `test/data/` |
+| Declarations | `typings/*.d.ts` |
+| Example | `example/index.js` |
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npm run build-ts` | Clean `dist/`, `typings/`, `coverage/`, then `tsc` |
+| `npm run compile` | `tsc` only |
+| `npm test` | Jest (coverage per `jest.config.js`) |
+| `npm run tslint` | TSLint `src/**/*.ts` |
+| `npm run clean` | Rimraf `dist`, `typings`, `coverage` |
+| `npm run build-doc` | Full build + JSDoc to `docs/` |
+
+## Test model and credentials
+
+- **Integration-style** tests against a **real MongoDB** (`Stack.connect()`, inserts, queries, teardown). **Not** live Contentstack HTTP API calls.
+- Default URI from merged **`src/config.ts`** (e.g. `mongodb://localhost:27017`); tests often use **`test/config.ts`** (`dbName` e.g. `sync-test`).
+- **No** committed `.env` for tests; override via **`contentStore`** (including `url`) in code. **Do not** commit production Mongo URIs or secrets.
+- **No** Testcontainers or CI Mongo service defined in-repo — local MongoDB is the documented path for developers running tests.
+
+## Skills index
+
+Canonical detail lives under **`skills/<kebab-case>/SKILL.md`**. See **[`skills/README.md`](skills/README.md)**.
+
+| Skill | `SKILL.md` |
+|-------|------------|
+| Dev workflow, hooks, CI | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) |
+| TypeScript / TSLint / `src/` layout | [`skills/typescript/SKILL.md`](skills/typescript/SKILL.md) |
+| DataSync MongoDB SDK behavior | [`skills/datasync-mongodb/SKILL.md`](skills/datasync-mongodb/SKILL.md) |
+| Testing | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) |
+| Code review | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) |
+
+## Using Cursor
+
+- Open **[`.cursor/rules/README.md`](.cursor/rules/README.md)** — the sole file in **`.cursor/rules/`** — for pointers to **`AGENTS.md`** and **`skills/`**.
+- Full guidance: **`skills/<name>/SKILL.md`** (attach or `@`-reference those paths in chat per your Cursor setup); there are **no** `.cursor/rules/*.mdc` files in this repo.
+
+## Contributor workflow (concise)
+
+- **`.husky/pre-commit`:** **Snyk** + **Talisman** when installed; `SKIP_HOOK=1` only if your team allows.
+- **CI:** `.github/workflows/` includes CodeQL, SCA, policy scans, **check-version-bump** — see each file for triggers.
+- **Version bump workflow** path filters may **not** list `src/`; maintainers may need to align the workflow with this layout (see [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md)).

package/package.json

@@ -1,7 +1,7 @@
 {
   "author": "Contentstack Ecosystem <ecosystem@contentstack.com>",
   "name": "@contentstack/datasync-mongodb-sdk",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "Mongodb query wrapper around contents synced via @contentstack/content-store-mongodb",
   "main": "dist/index.js",
   "scripts": {
@@ -18,7 +18,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "lodash": "^4.17.21",
+    "lodash": "^4.18.1",
     "mongodb": "^6.21.0",
     "npm-pack": "^1.0.0",
     "sift": "^17.1.3"

package/skills/README.md

@@ -0,0 +1,18 @@
+# Skills — `@contentstack/datasync-mongodb-sdk`
+
+**This directory is the source of truth** for detailed conventions (workflow, TypeScript/TSLint, DataSync MongoDB SDK behavior, tests, code review). Read **[`AGENTS.md`](../AGENTS.md)** at the repo root for the index, identity, and command tables; each skill is a folder with **`SKILL.md`** (YAML frontmatter: `name`, `description`).
+
+## When to use which skill
+
+| Skill folder | Use when |
+|--------------|----------|
+| [`dev-workflow/`](dev-workflow/SKILL.md) | Branches, `npm` scripts, Husky, CI, version bumps |
+| [`typescript/`](typescript/SKILL.md) | `tsconfig`, TSLint, `src/` layout, JSDoc |
+| [`datasync-mongodb/`](datasync-mongodb/SKILL.md) | `Stack`, MongoDB config, queries — DataSync vs CDA/CMA |
+| [`testing/`](testing/SKILL.md) | Jest, MongoDB test setup, fixtures, `jest.config.js` |
+| [`code-review/`](code-review/SKILL.md) | PR checklist, semver, terminology |
+
+## How to use these docs
+
+- **Humans / any tool:** Start at **`AGENTS.md`**, then open the relevant **`skills/<name>/SKILL.md`**.
+- **Cursor users:** **[`.cursor/rules/README.md`](../.cursor/rules/README.md)** (the only file under **`.cursor/rules/`**) points at **`AGENTS.md`** and **`skills/`**.

package/skills/code-review/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: code-review
+description: PR review for DataSync MongoDB SDK — JSDoc, compatibility, errors, tests, deps/SCA; terminology DataSync MongoDB SDK not CDA/CMA HTTP
+---
+
+# Code review — `@contentstack/datasync-mongodb-sdk`
+
+## When to use
+
+- Reviewing a PR that touches `src/`, `test/`, or public docs
+- Self-checking before request for review
+- Judging semver impact for Stack / config / query behavior
+
+## Instructions
+
+### Scope and terminology
+
+- This package is the **DataSync MongoDB SDK** (MongoDB over **synced** content). Do **not** call it the **CDA** or **CMA** **HTTP** SDK unless the change explicitly compares or documents migration.
+- Behavior should be validated with **MongoDB + Jest** tests, not live stack REST calls, unless the PR is explicitly about integration docs.
+
+### Public API and docs
+
+- **`Contentstack` / `Stack`** public surface should have accurate **JSDoc** consistent with `src/stack.ts`.
+- **README** / **`example/`** must match **`Stack.connect()`** and **`contentStore`** keys from **`src/config.ts`** and real usage.
+
+### Backward compatibility
+
+- Avoid breaking query result shape, **config** schema, or public method signatures without a **semver-major** plan.
+- Watch **locale**, **collection naming**, **reference depth**, **limit/skip** defaults.
+
+### Errors and messages
+
+- Prefer centralized strings in **`src/messages.ts`** where the codebase already does.
+
+### Correctness and null safety
+
+- Align with MongoDB driver and existing null checks in query chains.
+
+### Dependencies and security
+
+- New dependencies need justification; align with **`lodash` / `mongodb` / `sift`** patterns and **Snyk**/SCA expectations.
+
+### Tests
+
+- Behavioral changes in **`src/`** need matching **`test/`** updates and **`test/data/`** fixtures when document shapes change.
+
+### Optional severity
+
+| Level | Examples |
+|-------|----------|
+| Blocker | Wrong query results, data corruption risk, security issue, broken public API contract |
+| Major | Missing tests for core behavior, breaking change without version/docs strategy |
+| Minor | Style, non-user-facing refactors, doc nits |
+
+## References
+
+- [`../testing/SKILL.md`](../testing/SKILL.md)
+- [`../datasync-mongodb/SKILL.md`](../datasync-mongodb/SKILL.md)
+- [`../../AGENTS.md`](../../AGENTS.md)

package/skills/datasync-mongodb/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: datasync-mongodb
+description: DataSync MongoDB SDK — Stack, MongoDB connection, contentStore config, queries; not CDA/CMA HTTP
+---
+
+# SDK core and queries — `@contentstack/datasync-mongodb-sdk`
+
+## When to use
+
+- Implementing or changing query behavior, filters, or references in `src/stack.ts`
+- Adjusting defaults, URI validation, or locale/collection behavior (`src/config.ts`, `src/util.ts`)
+- Adding exports or user-facing errors (`src/index.ts`, `src/messages.ts`)
+
+## Instructions
+
+### Product model
+
+- **`@contentstack/datasync-mongodb-sdk`** queries **MongoDB** filled by Contentstack **DataSync** and stores such as **`@contentstack/content-store-mongodb`** (`package.json` description). It does **not** call Contentstack **Delivery** or **Management** REST APIs for normal reads.
+- **Stack** here is the query facade over **persisted sync data**, not an HTTP API stack or region endpoint.
+
+### Entry flow
+
+1. **`Contentstack.Stack(config, existingDb?)`** (`src/index.ts`) constructs **`Stack`** (`src/stack.ts`).
+2. **`Stack.connect()`** establishes the MongoDB client / database — call before queries (see README).
+3. Fluent API: **`contentType(uid)`**, **`entries()`**, **`assets()`**, filters, **`language()`**, **`includeReferences()`**, pagination, projections — see **`src/stack.ts`**.
+
+### Configuration
+
+- Config merges with **`src/config.ts`** defaults: e.g. **`contentStore.url`**, **`dbName`**, **`collection`** (asset / entry / schema names), **`locale`**, **`limit`**, **`skip`**, **`projections`**, **`options`** (MongoClient options), **`referenceDepth`**, **`indexes`**, internal type keys.
+- Optional second argument to **`Stack`**: an **existing** MongoDB connection for advanced scenarios.
+- **Indexes:** README recommends indexes on keys such as `_content_type_uid`, `uid`, `locale`, `updated_at` — align with ops for performance.
+
+### Query execution
+
+- **Driver:** **`mongodb`** (`MongoClient`, `Db`, collections).
+- **Filtering:** **`sift`** where used; **merge/sort:** **`lodash`** patterns in `stack.ts`.
+- **Validation:** **`validateConfig`**, **`validateURI`**, **`getCollectionName`** in **`src/util.ts`**.
+- **Errors:** prefer **`src/messages.ts`** for user-facing strings.
+
+### Async patterns
+
+- **`connect()`** / query methods follow existing **Promise** / `.then()` patterns in the codebase; match surrounding style when extending.
+
+### Retries
+
+- Document **MongoClient** / driver options under **`contentStore.options`** in config; **no** separate retry framework is defined in-repo — only what **`mongodb`** and merged config provide.
+
+### Scope
+
+- **`src/`** is the SDK core; **`example/`** is illustrative.
+
+### Where to change code
+
+| Concern | Start here |
+|---------|------------|
+| New operator or query path | `src/stack.ts` |
+| Defaults, merge behavior | `src/config.ts` |
+| URI / config validation | `src/util.ts` |
+| User-visible messages | `src/messages.ts` |
+| Public exports | `src/index.ts` |
+
+## References
+
+- [DataSync guide](https://www.contentstack.com/docs/guide/synchronization/contentstack-datasync)
+- [SDK docs](https://contentstack.github.io/datasync-mongodb-sdk/) (when linked from repo README)
+- [`../typescript/SKILL.md`](../typescript/SKILL.md)
+- [`../testing/SKILL.md`](../testing/SKILL.md)
+- [`../../AGENTS.md`](../../AGENTS.md)

package/skills/dev-workflow/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: dev-workflow
+description: Branches, npm scripts, Husky, CI, and version-bump expectations for @contentstack/datasync-mongodb-sdk
+---
+
+# Dev workflow — Contentstack DataSync MongoDB SDK
+
+## When to use
+
+- Onboarding or setting up locally
+- Before opening or updating a PR
+- Planning a release or editing `package.json` version
+
+## Instructions
+
+### Branches
+
+- No `development` / `master` policy is **encoded in this repo** — use your team’s Git flow (feature branches, PR merge targets).
+
+### Install and build
+
+```bash
+npm install
+npm run build-ts
+```
+
+`npm run build-ts` runs `clean` (rimraf `dist`, `typings`, `coverage`) then `tsc` (`package.json`).
+
+### Quality gates
+
+```bash
+npm run tslint   # TSLint — src/**/*.ts, tslint.json
+npm test         # Jest — no pretest script; ensure MongoDB available for integration tests
+```
+
+- **`npm run compile`** — `tsc` without clean (faster incremental builds).
+
+### PR expectations
+
+- Run **build** (`build-ts` or `compile` as appropriate), **tslint**, and **tests** when touching `src/` or query behavior.
+- **`.husky/pre-commit`** runs **Snyk** and **Talisman** when installed; use **`SKIP_HOOK=1`** only when your team allows bypassing checks.
+
+### Version bumps and CI
+
+- Version lives in **`package.json`**. Coordinate semver with maintainers for breaking **Stack** API or **contentStore** config shape changes.
+- **`.github/workflows/check-version-bump.yml`** flags missing `package.json` bumps for some “code changed” paths — its **`grep` patterns currently reference paths like `app.js`, `bin/`, `routes/`, not `src/`**. **Placeholder for maintainers:** align this workflow with **`src/`** / **`test/`** or confirm it is intentionally narrow.
+
+### Other workflows
+
+- **`.github/workflows/`** also includes **CodeQL**, **SCA**, **policy** scans — read each YAML for triggers.
+
+### Docs
+
+- **`npm run build-doc`** — requires successful TS output then JSDoc into **`docs/`**.
+
+## References
+
+- [`../testing/SKILL.md`](../testing/SKILL.md)
+- [`../typescript/SKILL.md`](../typescript/SKILL.md)
+- [`../../AGENTS.md`](../../AGENTS.md)

package/skills/testing/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: testing
+description: Jest + ts-jest for DataSync MongoDB SDK — real MongoDB integration tests, fixtures, jest.config.js, no live Contentstack HTTP
+---
+
+# Testing — `@contentstack/datasync-mongodb-sdk`
+
+## When to use
+
+- Adding or changing tests under `test/`
+- Debugging failures after `src/` changes
+- Understanding Jest ignores, coverage, or fixture layout
+
+## Instructions
+
+### Commands
+
+- **`npm test`** — runs **`jest`** only (`package.json`). **No `pretest`** — run **`npm run build-ts`** or **`npm run compile`** first if `dist/` / imports require it.
+- **`npm run build-ts`** — use when you need a clean compile before debugging.
+
+### Runner and config
+
+- **Jest** + **ts-jest**, **Node** environment (`jest.config.js`).
+- **`collectCoverage: true`** — reports under **`coverage/`** (JSON + HTML).
+- **`testMatch`:** `**/test/**/*.ts` (and `.js`).
+- **`testPathIgnorePatterns`:** `/test/data/*`, `/test/.*config.ts` — fixture/config paths are not treated as test files.
+- **`notify: true`** — may use `node-notifier` locally; optional in headless CI.
+
+### Layout
+
+| Path | Role |
+|------|------|
+| `test/**/*.ts` | Topic suites (`core.ts`, `queries.ts`, …) |
+| `test/data/*.ts` | Fixture documents imported into collections |
+| `test/config.ts` | Shared stack test config (e.g. `dbName`) |
+| `jest.config.js` | Match, ignore, coverage, transform |
+
+### Patterns
+
+- Tests typically **`Stack.connect()`**, insert fixtures via MongoDB driver, run Stack queries, assert, drop collections / **`Stack.close()`** in `afterAll` where used.
+- File names are **topic-based** (not required `*.test.ts`).
+
+### Environment and credentials
+
+- **Real MongoDB** at URL from merged config — default **`mongodb://localhost:27017`** in **`src/config.ts`** unless tests override **`contentStore.url`**.
+- **No** Delivery/Management API keys for core tests.
+- **No** `.env` contract in-repo; pass **`contentStore`** in code. **Do not** put production URIs in tests or CI secrets in the repo.
+- **No** Testcontainers / dockerized Mongo in this repo’s scripts — document **local MongoDB** for developers unless CI is extended.
+
+## References
+
+- [`../datasync-mongodb/SKILL.md`](../datasync-mongodb/SKILL.md)
+- [`../../AGENTS.md`](../../AGENTS.md)

package/skills/typescript/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: typescript
+description: TypeScript and TSLint for src/ — tsconfig, tslint.json, layout, JSDoc; no ESLint in this repo
+---
+
+# TypeScript (`src/`) — `@contentstack/datasync-mongodb-sdk`
+
+## When to use
+
+- Editing or adding files under `src/` or generated `typings/`
+- Aligning with compiler and TSLint settings
+- Choosing where new code belongs (`index.ts`, `stack.ts`, `config.ts`, `util.ts`, `messages.ts`)
+
+## Instructions
+
+### Tooling
+
+- **Compiler:** `tsconfig.json` — CommonJS, ES6 target, `noImplicitReturns`, `noUnusedLocals` / `noUnusedParameters`, declarations to **`typings/`**, output **`dist/`**.
+- **Lint:** **`npm run tslint`** with **`tslint.json`** on **`src/**/*.ts`**. This repo has **no ESLint** and **no `npm run lint`** script.
+
+### Style (TSLint)
+
+- Match `tslint.json`: e.g. 2-space indent, single quotes, no semicolons (`semicolon: never`), max line length 120, `ordered-imports`, `no-default-export` (entry composes via `src/index.ts`), `interface-name` with `I` prefix where used.
+
+### Layout
+
+- Public exports: **`src/index.ts`** (`Contentstack`, `Contentstack.Stack`).
+- Core query/connection logic: **`src/stack.ts`**.
+- Defaults: **`src/config.ts`**; validation/helpers: **`src/util.ts`**; copy: **`src/messages.ts`**.
+
+### JSDoc
+
+- Follow existing **`@public` / `@description`** patterns for symbols documented for **`npm run build-doc`**.
+
+### Logging
+
+- TSLint warns on several **`console`** methods in library code — avoid noisy logging in `src/`.
+
+### Dependencies
+
+- Do not assume HTTP/REST clients for core behavior — this SDK uses **MongoDB** + **lodash** + **sift** per **`package.json`**.
+
+## References
+
+- [`../datasync-mongodb/SKILL.md`](../datasync-mongodb/SKILL.md)
+- [`../../AGENTS.md`](../../AGENTS.md)