Added cursor rules and skills

.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.

.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).

.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.

.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=<Device>' test`  
+  Replace `<Device>` 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.

.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.

.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.

.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+    "snyk.advanced.organization": "18cb8ddb-8261-46fc-85fd-8b7025684b29",
+    "snyk.advanced.autoSelectOrganization": true
+}

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=<Device>' 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).

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];
 }
 

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

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).