Added cursor rules and skills

Author: reeshika-h

.cursor/rules/README.md

@@ -0,0 +1,23 @@
+# Cursor Rules – Contentstack Swift CDA SDK
+
+This directory contains Cursor AI rules that apply when working in this repository. Rules provide persistent context so the AI follows project conventions and Contentstack CDA patterns.
+
+## How rules are applied
+
+- **File-specific rules** use the `globs` frontmatter: they apply when you open or edit files matching that pattern.
+- **Always-on rules** use `alwaysApply: true`: they are included in every conversation in this project.
+
+## Rule index
+
+| File | Applies when | Purpose |
+|------|--------------|---------|
+| **dev-workflow.md** | (Reference only; no glob) | Core development workflow: branches, running tests, PR expectations. Read for process guidance. |
+| **swift.mdc** | Editing any `**/*.swift` file | Swift standards: naming, `Sources`/`Tests` layout, module **ContentstackSwift**, logging, optionals and error style. |
+| **contentstack-swift-cda.mdc** | Editing `Sources/**/*.swift` | CDA-specific patterns: Stack/ContentstackConfig, host/version/region/branch, URLSession, `Result`/`ResultsHandler`, alignment with Content Delivery API. |
+| **testing.mdc** | Editing `Tests/**/*.swift` | Testing patterns: XCTest, unit vs integration tests, fixtures, DVR where used. |
+| **code-review.mdc** | Always | PR/review checklist: API stability, error handling, backward compatibility, dependencies and security (e.g. SCA). |
+
+## Related
+
+- **AGENTS.md** (repo root) – Main entry point for AI agents: project overview, entry points, and pointers to rules and skills.
+- **skills/** – Reusable skill docs (Contentstack Swift CDA, testing, code review, framework) for deeper guidance on specific tasks.

.cursor/rules/code-review.mdc

@@ -0,0 +1,36 @@
+---
+description: PR and code review checklist – API stability, errors, compatibility, security
+alwaysApply: true
+---
+
+# Code Review Checklist – Contentstack Swift CDA SDK
+
+Use this checklist when reviewing pull requests or before opening a PR.
+
+## API design and stability
+
+- [ ] **Public API:** New or changed public types/methods/properties are necessary and clearly documented (Swift documentation comments where the project documents public API).
+- [ ] **Backward compatibility:** No breaking changes to public API unless explicitly called out and justified (e.g. major version).
+- [ ] **Naming:** Names are consistent with existing SDK style and CDA terminology.
+
+## Error handling and robustness
+
+- [ ] **Errors:** API failures surface through the SDK **`Error`** type and existing **`Result` / `ResultsHandler`** patterns (or `async`/`throws` where the API already uses them).
+- [ ] **Optionals:** No unintended force-unwraps; optional values are handled or documented; public contracts use optionals intentionally.
+- [ ] **Throws:** Thrown errors are appropriate for the API; callers can distinguish failure modes where the SDK promises it.
+
+## Dependencies and security
+
+- [ ] **Dependencies:** No new dependencies without justification; version bumps are intentional and do not introduce known vulnerabilities.
+- [ ] **SCA:** Address any security findings (e.g. from Snyk or similar) in the scope of the PR or in a follow-up.
+
+## Testing
+
+- [ ] **Coverage:** New or modified behavior is covered by unit and/or integration tests as appropriate.
+- [ ] **Test quality:** Tests are readable, stable (no flakiness), and follow project conventions (see **testing.mdc**).
+
+## Severity (optional)
+
+- **Blocker:** Must fix before merge (e.g. breaking public API without approval, security issue, no tests for new code).
+- **Major:** Should fix (e.g. inconsistent error handling, missing documentation on new public API).
+- **Minor:** Nice to fix (e.g. style, minor docs).

.cursor/rules/contentstack-swift-cda.mdc

@@ -0,0 +1,35 @@
+---
+description: Contentstack CDA patterns – Stack/ContentstackConfig, URLSession, callbacks, Content Delivery API
+globs: "Sources/**/*.swift"
+---
+
+# Contentstack Swift CDA – SDK Rules
+
+Apply when editing the SDK core (`Sources/`). Keep behavior aligned with the [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/).
+
+## Stack and ContentstackConfig
+
+- **Entry point:** `Contentstack.stack(apiKey:deliveryToken:environment:region:host:apiVersion:branch:config:)` returns a **`Stack`**. Pass **`ContentstackConfig`** for optional settings.
+- **Default host:** `Host.delivery` → **`cdn.contentstack.io`**; non-US regions adjust the host (see `Contentstack.stack` implementation).
+- **API version:** Default **`v3`** via the `apiVersion` parameter.
+- **Config:** `URLSessionConfiguration` (headers merged with SDK auth headers), `dateDecodingStrategy`, `timeZone`, `earlyAccess`, `urlSessionDelegate` for SSL pinning / session customization.
+- **Region / branch:** Use `ContentstackRegion` and optional `branch` on `stack(...)`; branch is sent as the `branch` header when set.
+
+## HTTP layer
+
+- **Requests** use **`URLSession`** created in **`Stack`** from `ContentstackConfig`. Do not bypass it for CDA calls.
+- **Headers:** Preserve `User-Agent` / `X-User-Agent` and authorization-related headers the SDK sets; additional headers may come from `sessionConfiguration.httpAdditionalHeaders`.
+- **Errors:** Map API failures to the SDK **`Error`** type and deliver them via **`Result`** / **`ResultsHandler`** (or existing async patterns).
+
+## Retry and resilience
+
+- The Swift SDK does not mirror the Java SDK’s **`RetryOptions` / interceptor** stack; resilience is primarily **`URLSession`** behavior and configuration. If adding retry or backoff, keep it configurable via **`ContentstackConfig`** / session and document defaults; align semantics with other CDA SDKs where practical.
+
+## Callbacks and async
+
+- Use existing completion types (**`ResultsHandler`**, `Result<..., Error>` closures) for async results. Do not introduce incompatible callback shapes without considering backward compatibility.
+- When adding `async` APIs, mirror existing naming and error mapping.
+
+## CDA concepts
+
+- **Entry, Query, Asset, Content Type, Sync, Taxonomy, Global Field** – follow existing types and method names and CDA semantics (query parameters, response models). When adding CDA features, align with the official Content Delivery API documentation.

.cursor/rules/dev-workflow.md

@@ -0,0 +1,29 @@
+# Development Workflow – Contentstack Swift CDA SDK
+
+Use this as the standard workflow when contributing to the Swift CDA SDK.
+
+## Branches
+
+- Use feature branches for changes (e.g. `feat/...`, `fix/...`).
+- Base work off the appropriate long-lived branch (e.g. `staging`, `development`, `main`) per team norms.
+
+## Running tests
+
+- **SPM (from repo root):** `swift test`
+- **SPM build only:** `swift build`
+- **Xcode:** Open `ContentstackSwift.xcodeproj`, select a scheme (e.g. **ContentstackSwift iOS Tests**), and run tests (⌘U).
+- **xcodebuild (example):**  
+  `xcodebuild -project ContentstackSwift.xcodeproj -scheme "ContentstackSwift iOS" -destination 'platform=iOS Simulator,name=iPhone 16' test`  
+  Adjust scheme and destination for macOS or tvOS as needed.
+
+Run tests before opening a PR. Tests that call the live CDA may require stack credentials (e.g. `Tests/config.json` or environment-specific setup—do not commit real tokens).
+
+## Pull requests
+
+- Ensure the build passes: `swift test` and/or Xcode tests for affected platforms.
+- Follow the **code-review** rule (see `.cursor/rules/code-review.mdc`) for the PR checklist.
+- Keep changes backward-compatible for public API; call out any breaking changes clearly.
+
+## Optional: TDD
+
+If the team uses TDD, follow RED–GREEN–REFACTOR when adding behavior: write a failing test first, then implement to pass, then refactor. The **testing** rule and **skills/testing** skill describe test structure and naming.

.cursor/rules/swift.mdc

@@ -0,0 +1,45 @@
+---
+description: Swift standards and ContentstackSwift module conventions for the CDA SDK
+globs: "**/*.swift"
+---
+
+# Swift Standards – Contentstack Swift CDA SDK
+
+Apply these conventions when editing Swift code in this repository.
+
+## Language and tooling
+
+- Match the **Swift** language version expected by `Package.swift` (swift-tools-version) and the Xcode project; avoid APIs that require a newer OS/SDK than declared platforms unless the change is intentional.
+- Prefer clear, idiomatic Swift over Objective-C patterns.
+
+## Module and layout
+
+- Library code lives under **`Sources/`** and builds the **`ContentstackSwift`** module.
+- Tests live under **`Tests/`** and depend on **ContentstackSwift** (see **testing.mdc** for test-specific rules).
+
+## Naming
+
+- **Types:** PascalCase (e.g. `Stack`, `ContentstackConfig`, `ContentstackResponse`).
+- **Methods and variables:** camelCase.
+- **Cases in enums:** lowerCamelCase unless matching external API raw values.
+
+## SDK structure
+
+- **`Contentstack`** is the factory; **`Stack`** owns networking and resource accessors (`contentType`, `asset`, `sync`, `taxonomy`, etc.).
+- Keep public surface area minimal; use `internal` for implementation details unless a wider API is required.
+
+## Logging
+
+- Use **`ContentstackLogger`** (or existing logging helpers in the SDK) consistently with current call sites.
+- Avoid `print` in library code unless that is already the established pattern for a specific diagnostic path.
+
+## Optionals and errors
+
+- Prefer **`Result<Success, Error>`** and **`ResultsHandler`** for async completion APIs where that is the existing pattern.
+- Avoid force unwraps (`!`); use `guard let` / `if let` or explicit error handling.
+- When adding `throws`, document which errors callers should handle.
+
+## General
+
+- Prefer value types where appropriate; reference types (`class`) are used where identity or inheritance is required (e.g. `Stack`).
+- Document public API with `///` comments where the project already documents symbols; keep examples aligned with real usage (`Contentstack.stack(...)`, `ContentstackConfig`).

.cursor/rules/testing.mdc

@@ -0,0 +1,34 @@
+---
+description: XCTest patterns, unit vs integration, fixtures and config for Contentstack Swift tests
+globs: "Tests/**/*.swift"
+---
+
+# Testing Rules – Contentstack Swift CDA SDK
+
+Apply when writing or editing tests. The project uses **XCTest** via SPM (`Tests/`) and Xcode test bundles.
+
+## Test naming and layout
+
+- **Unit tests:** Prefer descriptive type names ending in **`Test`** or **`Tests`** (e.g. `EntryTest`, `StackTest`, `QueryTest`) matching existing files under `Tests/`.
+- **Integration / API tests:** Classes that perform live HTTP against Contentstack often end in **`APITest`** or **`Test`** with network setup—follow existing peers (`*APITest.swift`, sync/asset/entry API tests). Use shared helpers (e.g. stack builders, `Tests/config.json`) where the suite already does.
+
+## XCTest usage
+
+- Subclass **`XCTestCase`** (or use extensions on it where the project does).
+- Use **`XCTAssert*`** macros; prefer specific assertions over generic truth checks.
+- Use **`XCTestExpectation`** for asynchronous completion handlers when not using async test methods.
+
+## Test data and credentials
+
+- **Fixtures:** JSON and resources under `Tests/` (e.g. `*.json`) are copied into test bundles via the Xcode project; keep them in sync when changing test expectations.
+- **Live stack:** Do not commit real API keys or delivery tokens. Use local `Tests/config.json` or CI secrets per team practice. Document required keys for integration tests in README or internal docs.
+
+## Unit vs integration
+
+- **Unit:** Mocked or offline data, fast, no network dependency where possible (DVR-cassette tests may apply).
+- **Integration:** Real `Stack` and CDA calls—gate on credentials and use reasonable timeouts to avoid hanging CI.
+
+## Quality
+
+- Keep tests deterministic; avoid time- and order-dependent assumptions unless documented.
+- When changing production behavior, update or add tests in the same area (query, entry, asset, sync, etc.).

AGENTS.md

@@ -0,0 +1,51 @@
+# Contentstack Swift CDA SDK – Agent Guide
+
+This document is the main entry point for AI agents working in this repository.
+
+## Project
+
+- **Name:** Contentstack Swift CDA SDK (contentstack-swift)
+- **Purpose:** Swift client for the Contentstack **Content Delivery API (CDA)**. It fetches content (entries, assets, content types, sync, taxonomy, global fields) from Contentstack for iOS, macOS, tvOS, watchOS, and Swift Package Manager consumers.
+- **Repo:** [contentstack-swift](https://github.com/contentstack/contentstack-swift)
+
+## Tech stack
+
+- **Language:** Swift (SPM minimum **swift-tools-version 5.6**; align with Xcode requirements in README)
+- **Build:** Swift Package Manager (`Package.swift`), **Xcode** (`ContentstackSwift.xcodeproj`) for multi-platform frameworks and CocoaPods (`ContentstackSwift.podspec`)
+- **Testing:** **XCTest** (`Tests/`), optional **DVR** (HTTP recording) for some tests; integration-style tests may use `Tests/config.json` / stack credentials
+- **HTTP:** **URLSession** (configured via `ContentstackConfig.sessionConfiguration`), optional **`CSURLSessionDelegate`** (SSL pinning / customization)
+- **Other:** [contentstack-utils-swift](https://github.com/contentstack/contentstack-utils-swift) (Rich text rendering)
+
+## Main entry points
+
+- **`Contentstack`** – Static factory: `Contentstack.stack(apiKey:deliveryToken:environment:region:host:apiVersion:branch:config:)` returns a `Stack`.
+- **`Stack`** – Main API surface: content types, entries, assets, sync, taxonomy, queries, cache policy, JSON decoding.
+- **`ContentstackConfig`** – Optional configuration: `URLSessionConfiguration`, date/time zone decoding, early access headers, `urlSessionDelegate`, user agent.
+- **Paths:** `Sources/` (library target **ContentstackSwift**), `Tests/` (test target **ContentstackTests**).
+
+## Commands
+
+- **SPM build:** `swift build`
+- **SPM tests:** `swift test`
+- **Xcode:** Open `ContentstackSwift.xcodeproj`, then build/test schemes such as **ContentstackSwift iOS**, **ContentstackSwift macOS**, **ContentstackSwift tvOS** (and matching test targets).
+- **xcodebuild (example – adjust simulator/OS):**  
+  `xcodebuild -project ContentstackSwift.xcodeproj -scheme "ContentstackSwift iOS" -destination 'platform=iOS Simulator,name=iPhone 16' build test`
+
+Run tests before opening a PR. API/integration tests that hit a live stack need valid credentials (see test helpers and `Tests/config.json` where applicable); do not commit secrets.
+
+## Rules and skills
+
+- **`.cursor/rules/`** – Cursor rules for this repo:
+  - **README.md** – Index of all rules and when each applies (globs / always-on).
+  - **dev-workflow.md** – Development workflow (branches, tests, PR expectations).
+  - **swift.mdc** – Applies to `**/*.swift`: Swift style, module layout, logging, optionals.
+  - **contentstack-swift-cda.mdc** – Applies to `Sources/**/*.swift`: CDA patterns, Stack/Config, host/version/region/branch, callbacks, alignment with Content Delivery API.
+  - **testing.mdc** – Applies to `Tests/**/*.swift`: test naming, unit vs integration, XCTest.
+  - **code-review.mdc** – Always applied: PR/review checklist (aligned with other Contentstack CDA SDKs).
+- **`skills/`** – Reusable skill docs:
+  - Use **contentstack-swift-cda** when implementing or changing CDA API usage or SDK core behavior.
+  - Use **testing** when adding or refactoring tests.
+  - Use **code-review** when reviewing PRs or before opening one.
+  - Use **framework** when changing config, URL session setup, or HTTP-related behavior (`ContentstackConfig`, `Stack` networking).
+
+Refer to `.cursor/rules/README.md` for when each rule applies and to `skills/README.md` for skill details.