From ad7fd57dc31d664ff6a330ece9112c27eb43371a Mon Sep 17 00:00:00 2001 From: reeshika-h Date: Fri, 20 Mar 2026 13:39:02 +0530 Subject: [PATCH 1/2] Added cursor rules and skills --- .cursor/rules/README.md | 23 ++++++++++ .cursor/rules/code-review.mdc | 36 ++++++++++++++++ .cursor/rules/contentstack-ios-cda.mdc | 36 ++++++++++++++++ .cursor/rules/dev-workflow.md | 27 ++++++++++++ .cursor/rules/ios.mdc | 43 ++++++++++++++++++ .cursor/rules/testing.mdc | 33 ++++++++++++++ .vscode/settings.json | 4 ++ AGENTS.md | 56 ++++++++++++++++++++++++ skills/README.md | 23 ++++++++++ skills/code-review/SKILL.md | 60 ++++++++++++++++++++++++++ skills/contentstack-ios-cda/SKILL.md | 52 ++++++++++++++++++++++ skills/framework/SKILL.md | 47 ++++++++++++++++++++ skills/testing/SKILL.md | 48 +++++++++++++++++++++ 13 files changed, 488 insertions(+) create mode 100644 .cursor/rules/README.md create mode 100644 .cursor/rules/code-review.mdc create mode 100644 .cursor/rules/contentstack-ios-cda.mdc create mode 100644 .cursor/rules/dev-workflow.md create mode 100644 .cursor/rules/ios.mdc create mode 100644 .cursor/rules/testing.mdc create mode 100644 .vscode/settings.json create mode 100644 AGENTS.md create mode 100644 skills/README.md create mode 100644 skills/code-review/SKILL.md create mode 100644 skills/contentstack-ios-cda/SKILL.md create mode 100644 skills/framework/SKILL.md create mode 100644 skills/testing/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 0000000..661dded --- /dev/null +++ b/.cursor/rules/README.md @@ -0,0 +1,23 @@ +# Cursor Rules – Contentstack iOS 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) | Development workflow: branches, running tests, PR expectations. Read for process guidance. | +| **ios.mdc** | `Contentstack/`, `ContentstackInternal/`, `ThirdPartyExtension/` `*.h` / `*.m` | Objective-C standards: naming, module layout, headers vs implementation, nullability, consistency with existing SDK style. | +| **contentstack-ios-cda.mdc** | `Contentstack/`, `ContentstackInternal/` `*.h` / `*.m` | CDA-specific patterns: Stack/Config, host/version/region/branch, HTTP entry points, retry behavior, blocks/callbacks, alignment with Content Delivery API. | +| **testing.mdc** | `ContentstackTest/**/*.h`, `ContentstackTest/**/*.m` | XCTest patterns: test class naming, unit vs network/integration-style tests, fixtures (`config.json`), stability. | +| **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, commands, pointers to rules and skills. +- **skills/** – Reusable skill docs (Contentstack iOS CDA, testing, code review, framework) for deeper guidance on specific tasks. diff --git a/.cursor/rules/code-review.mdc b/.cursor/rules/code-review.mdc new file mode 100644 index 0000000..f3ac1c8 --- /dev/null +++ b/.cursor/rules/code-review.mdc @@ -0,0 +1,36 @@ +--- +description: PR and code review checklist – API stability, errors, compatibility, security, testing +alwaysApply: true +--- + +# Code Review Checklist – Contentstack iOS CDA SDK + +Use this checklist when reviewing pull requests or before opening a PR. + +## API design and stability + +- [ ] **Public API:** New or changed public classes/methods/properties are necessary and documented (header comments / doc comments where the project documents API). +- [ ] **Backward compatibility:** No breaking changes to public API unless explicitly called out and justified (e.g. major semver bump per release policy). +- [ ] **Naming:** Method and type names are consistent with existing SDK style (Objective-C / Swift import names) and CDA terminology. + +## Error handling and robustness + +- [ ] **Errors:** API failures surface through existing patterns (`NSError **` out-parameters, failure blocks, or delegate callbacks as used in the touched code). +- [ ] **Nullability:** `NS_ASSUME_NONNULL` / `nullable` annotations stay accurate; no unintended force-unwraps or ignored errors in new paths. +- [ ] **Memory / threading:** Blocks and delegates retain cycles are avoided; main-queue vs background behavior matches existing networking code. + +## Dependencies and security + +- [ ] **Dependencies:** No new third-party or vendored code 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 XCTest unit and/or integration-style 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). diff --git a/.cursor/rules/contentstack-ios-cda.mdc b/.cursor/rules/contentstack-ios-cda.mdc new file mode 100644 index 0000000..1610ed8 --- /dev/null +++ b/.cursor/rules/contentstack-ios-cda.mdc @@ -0,0 +1,36 @@ +--- +description: Contentstack CDA patterns – Stack/Config, HTTP, retry, callbacks, Content Delivery API +globs: + - "Contentstack/**/*.{h,m}" + - "ContentstackInternal/**/*.{h,m}" +--- + +# Contentstack iOS CDA – SDK Rules + +Apply when editing the SDK core (`Contentstack/`, `ContentstackInternal/`). Keep behavior aligned with the [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/). + +## Stack and Config + +- **Entry point:** `+[Contentstack stackWithAPIKey:accessToken:environmentName:]` and `stackWithAPIKey:accessToken:environmentName:config:` return a **`Stack`**. Use **`Config`** for optional settings (host, region, branch, delegate, early access). +- **Defaults:** Follow existing **`Config`** initialization (host/version behavior as implemented in `Config` / stack setup). +- **Region / branch:** Support regional endpoints and branch delivery via **`Config`** properties, consistent with CDA docs and current stack URL building (`CSIOAPIURLs`, etc.). + +## HTTP layer + +- **Requests** should flow through **`CSIOCoreHTTPNetworking`** and **`CSURLSessionManager`** (and related internal types). Do not bypass the shared session stack for CDA calls without a strong reason. +- **Headers:** Preserve User-Agent, access token, environment, and other required CDA headers as built in existing request code (`CSIOConstants`, stack configuration). +- **Errors:** Map API failures to existing patterns (`NSError`, failure blocks, or error callbacks) so app code receives consistent semantics. + +## Retry and resilience + +- Retry logic for transient failures lives in the networking layer (e.g. **`CSIOCoreHTTPNetworking`** handling of status / error codes). When changing retry behavior, keep defaults and caps consistent with CDA-friendly backoff and document any behavior change. +- Unlike some other SDKs, retry is not always exposed as a separate public **`Config`** surface; prefer adjusting the internal implementation coherently. + +## Callbacks and async + +- Use **blocks**, delegates (`CSURLSessionDelegate`), and existing completion patterns already used on **`Stack`**, **`Entry`**, **`Query`**, **`Asset`**, **`SyncStack`**, etc. +- Do not change public callback signatures without a compatibility plan (semver / migration note). + +## CDA concepts + +- **Entry, Query, Asset, Content Type, Sync, Taxonomy, AssetLibrary, Group, QueryResult** – follow existing class names and CDA semantics (query parameters, response parsing). When adding CDA features, align with the official Content Delivery API documentation and with other Contentstack CDA SDKs where practical. diff --git a/.cursor/rules/dev-workflow.md b/.cursor/rules/dev-workflow.md new file mode 100644 index 0000000..6ea8d0a --- /dev/null +++ b/.cursor/rules/dev-workflow.md @@ -0,0 +1,27 @@ +# Development Workflow – Contentstack iOS CDA SDK + +Use this as the standard workflow when contributing to the iOS CDA SDK. + +## Branches + +- Use feature branches for changes (e.g. `feat/...`, `fix/...`). +- Base work off the appropriate long-lived branch (e.g. `staging`, `development`) per team norms. + +## Running tests + +- **From Xcode:** Select scheme **Contentstack**, then **Product → Test** (`⌘U`). +- **Command line:** + `xcodebuild -project Contentstack.xcodeproj -scheme Contentstack -destination 'platform=iOS Simulator,name=' test` + Replace `` with an installed simulator (list with `xcrun simctl list devices available`). + +Run tests before opening a PR. Tests that call the live CDA may require **`ContentstackTest/config.json`** (API key, delivery token, environment, host, etc.)—keep secrets out of git; follow existing test setup patterns. + +## Pull requests + +- Ensure the project builds and tests pass locally. +- 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 in the PR description. + +## 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. diff --git a/.cursor/rules/ios.mdc b/.cursor/rules/ios.mdc new file mode 100644 index 0000000..2163b36 --- /dev/null +++ b/.cursor/rules/ios.mdc @@ -0,0 +1,43 @@ +--- +description: Objective-C standards and Contentstack iOS SDK layout for CDA sources +globs: + - "Contentstack/**/*.{h,m}" + - "ContentstackInternal/**/*.{h,m}" + - "ThirdPartyExtension/**/*.{h,m}" +--- + +# iOS SDK Standards – Contentstack iOS CDA SDK + +Apply these conventions when editing Objective-C code in the SDK (not test targets). + +## Language and runtime + +- **Objective-C** with Apple’s modern conventions: use `NS_ASSUME_NONNULL_BEGIN` / `END` (or explicit `nullable` / `nonnull`) on public headers where the project already does. +- **Swift consumers** import the module; avoid breaking Swift names without good reason (Objective-C names map to Swift automatically). + +## Layout and modules + +- **Public API** lives under **`Contentstack/`** (headers shipped via `public_header_files` in the podspec). +- **Internal implementation** lives under **`ContentstackInternal/`** (HTTP, URLs, constants, extensions). Do not expose internal headers as public API without an explicit decision. +- **Vendored / shared code** under **`ThirdPartyExtension/`** (e.g. `CSURLSessionManager`, markdown, ISO8601). Keep changes minimal and consistent with upstream vendoring policy. + +## Naming + +- **Classes:** Prefix or unprefixed names as established in this SDK (`Stack`, `Config`, `CSIOCoreHTTPNetworking`, etc.); do not introduce conflicting generic names. +- **Methods:** Objective-C style, descriptive selectors; match existing patterns for “fetch”, “callback”, “withConfig:”, etc. +- **Categories:** Use project prefixes on category methods to avoid collisions (`cs_` or existing project convention). +- **Test classes:** See **testing.mdc** (`*Test` XCTest case naming). + +## Headers + +- Public declarations belong in **`Contentstack/*.h`**; import umbrella patterns consistent with **`Contentstack.h`**. +- Use forward declarations (`@class`) in headers when possible to reduce compile coupling. + +## Documentation + +- Public API should retain or extend the existing block-comment style in headers (parameters, return value, Obj-C / Swift snippets where already used). + +## General + +- Prefer explicit error handling over silent failure when adding new async or network paths. +- Match existing memory management (ARC); avoid introducing non-ARC patterns. diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc new file mode 100644 index 0000000..136e4e0 --- /dev/null +++ b/.cursor/rules/testing.mdc @@ -0,0 +1,33 @@ +--- +description: XCTest patterns, unit vs integration-style tests, fixtures, stability +globs: + - "ContentstackTest/**/*.{h,m}" +--- + +# Testing Rules – Contentstack iOS CDA SDK + +Apply when writing or editing tests in the **ContentstackTest** target. + +## Test naming and layout + +- **XCTest** case classes: suffix **`Test`** (e.g. `ContentstackMainTest`, `QueryResultTest`, `SyncTest`) matching existing files under **`ContentstackTest/`**. +- **Test methods:** `- (void)test...` with descriptive names; group related tests with `#pragma mark` sections where the file already uses that style. + +## Unit vs integration-style + +- **Unit-style:** Mock or avoid network where possible; assert parsing, model behavior, and edge cases quickly. +- **Integration-style:** Tests that call the live CDA require valid credentials—typically via **`config.json`** in the test bundle (see `ContentstackMainTest` and similar). Do not commit real tokens; document required keys for local/CI runs. + +## XCTest usage + +- Use **`XCTAssert*`** macros; use **`XCTestExpectation`** / **`waitForExpectationsWithTimeout:`** for async flows. +- Use **`setUp`** / **`tearDown`** for fixtures; load JSON or plist resources from **`[NSBundle bundleForClass:[self class]]`** when the project uses bundle resources. + +## Stability + +- Avoid time-dependent assertions unless necessary; prefer reasonable timeouts for network tests. +- Do not introduce flaky ordering assumptions or shared mutable global state across tests without synchronization. + +## Coverage + +- The **Contentstack** scheme enables code coverage for the **Contentstack** framework target. Add or extend tests when changing production behavior; do not drop coverage for critical paths without replacement tests. diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..64557a7 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,4 @@ +{ + "snyk.advanced.organization": "18cb8ddb-8261-46fc-85fd-8b7025684b29", + "snyk.advanced.autoSelectOrganization": true +} \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0cdc59e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,56 @@ +# Contentstack iOS CDA SDK – Agent Guide + +This document is the main entry point for AI agents working in this repository. + +## Project + +- **Name:** Contentstack iOS CDA SDK (contentstack-ios) +- **Purpose:** iOS client for the Contentstack **Content Delivery API (CDA)**. It fetches content (entries, assets, content types, sync, taxonomy) from Contentstack for iOS apps (Objective-C primary API; Swift-compatible headers). +- **Repo:** [contentstack-ios](https://github.com/contentstack/contentstack-ios) + +## Tech stack + +- **Languages:** Objective-C (public SDK surface), with Swift-callable APIs via generated/bridged headers +- **IDE / build:** Xcode, `Contentstack.xcodeproj` +- **Distribution:** CocoaPods (`Contentstack.podspec`); no Swift Package Manager manifest in-repo today +- **HTTP:** `NSURLSession` via `CSURLSessionManager` and `CSIOCoreHTTPNetworking` (internal) +- **Testing:** XCTest, target **ContentstackTest** (`ContentstackTest.xctest`), scheme **Contentstack** (tests enabled; code coverage for **Contentstack** framework) + +## Main entry points + +- **`Contentstack`** – Factory: `+[Contentstack stackWithAPIKey:accessToken:environmentName:]` and `stackWithAPIKey:accessToken:environmentName:config:` return a **`Stack`**. +- **`Stack`** – Main API surface: content types, entries, queries, assets, asset library, sync, taxonomy, etc. +- **`Config`** – Optional settings: host, region, version (read-only where applicable), branch, URL session delegate, early access headers. +- **Paths (source):** `Contentstack/` (public headers + implementation), `ContentstackInternal/` (HTTP, URLs, constants, internal helpers), `ThirdPartyExtension/` (networking session layer, markdown, ISO8601). +- **Paths (tests):** `ContentstackTest/` + +## Commands + +- **Build framework:** + `xcodebuild -project Contentstack.xcodeproj -scheme Contentstack -destination 'generic/platform=iOS' -configuration Debug build` +- **Run tests:** + `xcodebuild -project Contentstack.xcodeproj -scheme Contentstack -destination 'platform=iOS Simulator,name=' test` + Pick a simulator you have installed (e.g. **iPhone 16**). Tests may require **`ContentstackTest/config.json`** (or equivalent) with stack credentials for integration-style cases—do not commit secrets. +- **CocoaPods lint (maintainers):** + `pod lib lint Contentstack.podspec` + +Use **Product → Test** in Xcode as an alternative to `xcodebuild test`. + +## Rules and skills + +- **`.cursor/rules/`** – Cursor rules for this repo: + - **README.md** – Index of all rules and when each applies. + - **dev-workflow.md** – Branches, tests, PR expectations. + - **ios.mdc** – Applies to SDK Objective-C sources: style, structure, naming. + - **contentstack-ios-cda.mdc** – Applies to SDK core: CDA patterns, Stack/Config, HTTP/retry, callbacks, CDA alignment. + - **testing.mdc** – Applies to **ContentstackTest**: XCTest naming, unit vs integration-style tests. + - **code-review.mdc** – Always applied: PR/review checklist (aligned with other Contentstack CDA SDKs). +- **`skills/`** – Reusable skill docs: + - **contentstack-ios-cda** – CDA implementation and SDK core behavior. + - **testing** – Adding or refactoring tests. + - **code-review** – PR review or pre-submit checklist. + - **framework** – Config, HTTP session layer, retry behavior, and networking internals. + +Refer to `.cursor/rules/README.md` for the rule index and to `skills/README.md` for when to use each skill. + +For cross-SDK alignment, see the Java CDA SDK’s **AGENTS.md** and `.cursor/rules/` in [contentstack-java](https://github.com/contentstack/contentstack-java) (patterns are analogous; APIs and build tools differ). diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..2f90374 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,23 @@ +# Skills – Contentstack iOS CDA SDK + +This directory contains **skills**: reusable guidance for AI agents (and developers) on specific tasks. Each skill is a folder with a `SKILL.md` file. + +## When to use which skill + +| Skill | Use when | +|-------|----------| +| **contentstack-ios-cda** | Implementing or changing CDA features: Stack/Config, entries, assets, content types, sync, taxonomy, query results, alignment with the Content Delivery API, and public callback patterns. | +| **testing** | Writing or refactoring **ContentstackTest** tests: XCTest, fixtures (`config.json`), async expectations, unit vs integration-style coverage. | +| **code-review** | Reviewing a PR or preparing your own: API design, errors, backward compatibility, dependencies/security, test coverage (see shared checklist with other CDA SDKs). | +| **framework** | Changing **Config**, URL/session configuration, **`CSIOCoreHTTPNetworking`**, **`CSURLSessionManager`**, retry behavior, or internal request/response flow. | + +## How agents should use skills + +- **contentstack-ios-cda:** Apply when editing SDK production code under `Contentstack/` or `ContentstackInternal/` for CDA behavior. Follow Stack/Config entry points and existing block/delegate error patterns. +- **testing:** Apply when creating or modifying `ContentstackTest/*`. Match existing `*Test` class naming and resource loading patterns. +- **code-review:** Apply when performing or simulating a PR review. Use the checklist in `.cursor/rules/code-review.mdc` and optional severity levels. +- **framework:** Apply when touching networking internals or Config-related behavior. Keep session, retry, and error propagation consistent. + +Each skill’s `SKILL.md` contains more detailed instructions and file references. + +For parity with sibling SDKs, compare with **contentstack-java** `skills/` (same intent; Java-specific commands and types differ). diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000..51c1b58 --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,60 @@ +--- +name: code-review +description: Use when reviewing PRs or before opening a PR – API design, errors, memory/threading, backward compatibility, dependencies, security, XCTest quality +--- + +# Code Review – Contentstack iOS CDA SDK + +Use this skill when performing or preparing a pull request review for the iOS CDA SDK. + +## When to use + +- Reviewing someone else’s PR. +- Self-reviewing your own PR before submission. +- Checking that changes meet project standards (API, errors, compatibility, tests, security). + +## Instructions + +Work through the checklist below. Optionally tag items with severity: **Blocker**, **Major**, **Minor**. The canonical short checklist lives in `.cursor/rules/code-review.mdc` (aligned with **contentstack-java** and other CDA SDKs). + +### 1. API design and stability + +- [ ] **Public API:** New or changed public headers are necessary and documented (header comments / usage examples consistent with the repo). +- [ ] **Backward compatibility:** No breaking changes to public Objective-C / Swift-visible API without agreement (major version or explicit migration). +- [ ] **Naming:** Consistent with existing SDK and CDA terminology (`Stack`, `Entry`, `Query`, `Config`, etc.). + +**Severity:** Breaking public API without approval = **Blocker**. Missing docs on new public API = **Major**. + +### 2. Error handling and robustness + +- [ ] **Errors:** Failures use `NSError`, failure blocks, or delegates as appropriate for the module. +- [ ] **Nullability:** Annotations remain correct; no ignored errors in new code paths. +- [ ] **Memory / concurrency:** No obvious retain cycles; threading matches existing networking patterns. + +**Severity:** Wrong or missing error handling in new code = **Major**. + +### 3. Dependencies and security + +- [ ] **Dependencies:** Podspec / vendored code changes are justified; versions do not introduce known critical issues. +- [ ] **SCA:** Security findings (Snyk, Dependabot, etc.) are addressed or tracked. + +**Severity:** New critical/high vulnerability = **Blocker**. + +### 4. Testing + +- [ ] **Coverage:** New or modified behavior has XCTest coverage where feasible. +- [ ] **Conventions:** Test classes follow `*Test` naming; async tests use expectations and sane timeouts. +- [ ] **Quality:** Tests are deterministic and readable. + +**Severity:** No tests for new behavior = **Blocker** (unless explicitly out of scope). Flaky tests = **Major**. + +### 5. Optional severity summary + +- **Blocker:** Must fix before merge (e.g. breaking API without approval, security issue, no tests for new code). +- **Major:** Should fix (e.g. inconsistent error handling, missing public API docs, flaky tests). +- **Minor:** Nice to fix (e.g. style, minor docs). + +## References + +- Project rule: `.cursor/rules/code-review.mdc` +- Testing skill: `skills/testing/SKILL.md` diff --git a/skills/contentstack-ios-cda/SKILL.md b/skills/contentstack-ios-cda/SKILL.md new file mode 100644 index 0000000..91eb70a --- /dev/null +++ b/skills/contentstack-ios-cda/SKILL.md @@ -0,0 +1,52 @@ +--- +name: contentstack-ios-cda +description: Use when implementing or changing CDA features – Stack/Config, entries, assets, sync, taxonomy, query, HTTP entry points, retry, callbacks, and Content Delivery API alignment +--- + +# Contentstack iOS CDA SDK – CDA Implementation + +Use this skill when implementing or changing Content Delivery API (CDA) behavior in the iOS SDK. + +## When to use + +- Adding or modifying **Stack**, **Entry**, **Query**, **Asset**, **ContentType**, **SyncStack**, **Taxonomy**, **AssetLibrary**, **Group**, or **QueryResult** behavior. +- Changing **Config** (host, region, branch, delegate, early access) or how the stack builds API URLs. +- Adjusting how requests are issued or errors returned at the boundary between public API and **`CSIOCoreHTTPNetworking`**. + +## Instructions + +### Stack and Config + +- **Entry point:** `+[Contentstack stackWithAPIKey:accessToken:environmentName:]` and `stackWithAPIKey:accessToken:environmentName:config:`. +- **Config:** Optional `Config` for custom host, region, branch, `id`, early access feature flags, etc. +- **Reference:** `Contentstack.h` / `Contentstack.m`, `Stack.h` / `Stack.m`, `Config.h` / `Config.m`. + +### CDA resources + +- **Entries / content types / queries:** Follow existing `Stack` → content type → entry / query flows and completion-handler patterns. +- **Assets:** Use **Asset**, **AssetLibrary**, and existing fetch/query APIs. +- **Sync:** Use **SyncStack** and existing pagination/token patterns. +- **Taxonomy:** Use **Taxonomy** and related stack APIs. +- **Official API:** Align with [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/) for parameters, responses, and semantics. + +### HTTP and retry + +- **HTTP:** CDA traffic goes through **`CSIOCoreHTTPNetworking`** and **`CSURLSessionManager`**. Preserve header construction and URL schemes used elsewhere. +- **Retry:** Implemented inside the HTTP layer (e.g. handling of specific error codes with backoff). When changing retry, verify behavior against CDA expectations and avoid unbounded retries. + +### Errors and callbacks + +- Surface failures through **`NSError`**, failure blocks, or delegates consistent with the class being edited. +- Do not change public callback contracts without a semver/compatibility plan. + +## Key types (indicative) + +- **Entry:** `Contentstack`, `Stack`, `Config` +- **CDA:** `Entry`, `Query`, `Asset`, `AssetLibrary`, `ContentType`, `SyncStack`, `Taxonomy`, `Group`, `QueryResult` +- **HTTP (internal):** `CSIOCoreHTTPNetworking`, `CSURLSessionManager`, `CSIOAPIURLs`, `CSIOConstants` + +## References + +- [Content Delivery API – Contentstack Docs](https://www.contentstack.com/docs/apis/content-delivery-api/) +- Project rules: `.cursor/rules/contentstack-ios-cda.mdc`, `.cursor/rules/ios.mdc` +- **AGENTS.md** – commands and directory map diff --git a/skills/framework/SKILL.md b/skills/framework/SKILL.md new file mode 100644 index 0000000..0975a80 --- /dev/null +++ b/skills/framework/SKILL.md @@ -0,0 +1,47 @@ +--- +name: framework +description: Use when changing Config, URL/session setup, CSIOCoreHTTPNetworking, CSURLSessionManager, retry behavior, or internal request flow +--- + +# Framework – Contentstack iOS CDA SDK + +Use this skill when changing configuration, URL/session behavior, or the internal HTTP stack (not the high-level CDA object model). + +## When to use + +- Modifying **`Config`** properties or how **`Stack`** applies config to base URLs and headers. +- Changing **`CSIOCoreHTTPNetworking`** request building, response handling, or retry loops. +- Changing **`CSURLSessionManager`**, session configuration, delegate wiring, or operation queues. +- Adjusting **`CSIOAPIURLs`**, **`CSIOConstants`**, caching (`CSIOURLCache`), or internal extensions (`NSObject+Extensions`). + +## Instructions + +### Config and Stack + +- **Config** exposes delivery-related options (host, region, branch, session delegate, early access). Preserve default behavior expected by existing apps when changing initialization or defaults. +- **Stack** ties config to the internal network object; keep reference lifetimes and teardown (`cancelAllRequestsOfStack:`) coherent. + +### HTTP session layer + +- **`CSURLSessionManager`** wraps **`NSURLSession`** with success/failure blocks and delegate callbacks. Changes here affect all CDA traffic—verify timeouts, TLS behavior, and background vs foreground assumptions. +- Do not fragment session usage: new CDA calls should use the same stack/session path as existing ones unless intentionally designing a new client. + +### Retry and resilience + +- Retry is implemented in **`CSIOCoreHTTPNetworking`** (e.g. handling of transient errors with bounded retries and backoff). When adjusting retry conditions or counts, document behavior and consider alignment with other Contentstack CDA SDKs’ retry policies where applicable. + +### Errors + +- Propagate **`NSError`** and API error payloads through the same paths used today so higher layers (`Stack`, `Entry`, `Query`, etc.) remain consistent. + +## Key files (indicative) + +- **Config / stack wiring:** `Config.m`, `Stack.m` +- **HTTP:** `CSIOCoreHTTPNetworking.m`, `CSIOCoreHTTPNetworking.h` +- **Session:** `CSURLSessionManager.m`, `CSURLSessionManager.h`, `CSURLSessionDelegate.h` +- **URLs / constants:** `CSIOAPIURLs.m`, `CSIOConstants.m` + +## References + +- Project rules: `.cursor/rules/contentstack-ios-cda.mdc`, `.cursor/rules/ios.mdc` +- CDA skill: `skills/contentstack-ios-cda/SKILL.md` for public CDA API changes that depend on framework behavior diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 0000000..565aac7 --- /dev/null +++ b/skills/testing/SKILL.md @@ -0,0 +1,48 @@ +--- +name: testing +description: Use when writing or refactoring ContentstackTest – XCTest, fixtures, async, naming, unit vs integration-style +--- + +# Testing – Contentstack iOS CDA SDK + +Use this skill when adding or refactoring tests in the **ContentstackTest** target. + +## When to use + +- Writing new XCTest cases or methods. +- Adding bundle resources (e.g. JSON fixtures) for tests. +- Debugging flaky or slow network tests. + +## Instructions + +### XCTest and layout + +- Tests live under **`ContentstackTest/`** and compile into **`ContentstackTest.xctest`** (scheme **Contentstack**). +- **Class naming:** `*Test` (e.g. `ContentstackMainTest`, `QueryAdvancedTest`). +- **Method naming:** `- (void)testFeatureName` or similar descriptive selectors. + +### Fixtures and credentials + +- Integration-style tests often load **`config.json`** from the test bundle (see `ContentstackMainTest`). Required keys should match what existing tests read (`api_key`, `delivery_token`, `environment`, `host`, etc.). +- Never commit production tokens. For CI, use secrets or skip network tests when credentials are missing (follow patterns already in the suite if present). + +### Async and timeouts + +- Use **`XCTestExpectation`** and **`waitForExpectationsWithTimeout:`** (or `waitForExpectations`) for asynchronous stack/entry/query completion handlers. +- Choose timeouts appropriate to network latency; avoid excessively short timeouts that flake on slow networks. + +### Unit vs integration-style + +- Prefer fast, deterministic unit tests for pure logic (parsing, edge cases) when you can isolate behavior. +- Use real-stack tests sparingly and only when validating end-to-end CDA integration. + +### Execution + +- **Xcode:** `⌘U` with scheme **Contentstack**. +- **CLI:** `xcodebuild -project Contentstack.xcodeproj -scheme Contentstack -destination 'platform=iOS Simulator,name=' test` + +## References + +- `ContentstackTest/*.m` – existing patterns +- Project rule: `.cursor/rules/testing.mdc` +- **AGENTS.md** – test target and command summary From 5767758057e740a6e62fc27f4c2d8e2f06b9ec6c Mon Sep 17 00:00:00 2001 From: reeshika-h Date: Fri, 20 Mar 2026 13:44:03 +0530 Subject: [PATCH 2/2] Update LICENSE year to 2026 and add nil check for JSONData in jsonStringFromArray method in NSObject+Extensions.m --- ContentstackInternal/NSObject+Extensions.m | 1 + LICENSE | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/ContentstackInternal/NSObject+Extensions.m b/ContentstackInternal/NSObject+Extensions.m index 599cf72..a0fdc21 100755 --- a/ContentstackInternal/NSObject+Extensions.m +++ b/ContentstackInternal/NSObject+Extensions.m @@ -294,6 +294,7 @@ - (NSArray *)arrayFromJSONData:(NSData *)data { - (NSString *)jsonStringFromArray:(NSArray*)array { if (array == nil) { return nil; } NSData *JSONData = [NSJSONSerialization dataWithJSONObject:array options:0 error:NULL]; + if (JSONData == nil) { return nil; } return [[NSString alloc] initWithData:JSONData encoding:NSUTF8StringEncoding]; } diff --git a/LICENSE b/LICENSE index 3851325..4ea4612 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2012-2025 Contentstack +Copyright (c) 2012-2026 Contentstack Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal