AGENTS.md

1# Contentstack iOS CDA SDK – Agent Guide
2 
3This document is the main entry point for AI agents working in this repository.
4 
5## Project
6 
7- **Name:** Contentstack iOS CDA SDK (contentstack-ios)
8- **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).
9- **Repo:** [contentstack-ios](https://github.com/contentstack/contentstack-ios)
10 
11## Tech stack
12 
13- **Languages:** Objective-C (public SDK surface), with Swift-callable APIs via generated/bridged headers
14- **IDE / build:** Xcode, `Contentstack.xcodeproj`
15- **Distribution:** CocoaPods (`Contentstack.podspec`); no Swift Package Manager manifest in-repo today
16- **HTTP:** `NSURLSession` via `CSURLSessionManager` and `CSIOCoreHTTPNetworking` (internal)
17- **Testing:** XCTest, target **ContentstackTest** (`ContentstackTest.xctest`), scheme **Contentstack** (tests enabled; code coverage for **Contentstack** framework)
18 
19## Main entry points
20 
21- **`Contentstack`** – Factory: `+[Contentstack stackWithAPIKey:accessToken:environmentName:]` and `stackWithAPIKey:accessToken:environmentName:config:` return a **`Stack`**.
22- **`Stack`** – Main API surface: content types, entries, queries, assets, asset library, sync, taxonomy, etc.
23- **`Config`** – Optional settings: host, region, version (read-only where applicable), branch, URL session delegate, early access headers.
24- **Paths (source):** `Contentstack/` (public headers + implementation), `ContentstackInternal/` (HTTP, URLs, constants, internal helpers), `ThirdPartyExtension/` (networking session layer, markdown, ISO8601).
25- **Paths (tests):** `ContentstackTest/`
26 
27## Commands
28 
29- **Build framework:**  
30  `xcodebuild -project Contentstack.xcodeproj -scheme Contentstack -destination 'generic/platform=iOS' -configuration Debug build`
31- **Run tests:**  
32  `xcodebuild -project Contentstack.xcodeproj -scheme Contentstack -destination 'platform=iOS Simulator,name=<Device>' test`  
33  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.
34- **CocoaPods lint (maintainers):**  
35  `pod lib lint Contentstack.podspec`
36 
37Use **Product → Test** in Xcode as an alternative to `xcodebuild test`.
38 
39## Rules and skills
40 
41- **`.cursor/rules/`** – Cursor rules for this repo:
42  - **README.md** – Index of all rules and when each applies.
43  - **dev-workflow.md** – Branches, tests, PR expectations.
44  - **ios.mdc** – Applies to SDK Objective-C sources: style, structure, naming.
45  - **contentstack-ios-cda.mdc** – Applies to SDK core: CDA patterns, Stack/Config, HTTP/retry, callbacks, CDA alignment.
46  - **testing.mdc** – Applies to **ContentstackTest**: XCTest naming, unit vs integration-style tests.
47  - **code-review.mdc** – Always applied: PR/review checklist (aligned with other Contentstack CDA SDKs).
48- **`skills/`** – Reusable skill docs:
49  - **contentstack-ios-cda** – CDA implementation and SDK core behavior.
50  - **testing** – Adding or refactoring tests.
51  - **code-review** – PR review or pre-submit checklist.
52  - **framework** – Config, HTTP session layer, retry behavior, and networking internals.
53 
54Refer to `.cursor/rules/README.md` for the rule index and to `skills/README.md` for when to use each skill.
55 
56For 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).
57