Skip to content

Commit 04ed424

Browse files
andygrueningtolgahan-arikan
andygruening
and
tolgahan-arikan
authored
feat(ci): add Claude workflows and project documentation (#6)
* checkout repository in claude workflows * add agent-doctor scaffolding and CI improvements * docs: clarify PR CI coverage * ci: skip Claude review for Dependabot PRs --------- Co-authored-by: Tolgahan <tolgahan.arikan@gmail.com>
1 parent e06b910 commit 04ed424

11 files changed

Lines changed: 477 additions & 0 deletions

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
## Summary
2+
3+
<!-- What does this PR do and why? 1–3 sentences. -->
4+
5+
> PR title must follow Conventional Commits, e.g. `feat(auth): short description`.
6+
> See https://www.conventionalcommits.org
7+
8+
## Changes
9+
10+
-
11+
12+
## Testing
13+
14+
<!-- How was this verified? Commands run, manual steps, screenshots. -->
15+
16+
- [ ] `yarn lint` passes
17+
- [ ] `yarn typecheck` passes
18+
- [ ] `yarn prepare` (library build) succeeds
19+
- [ ] Native layer unchanged **or** manually verified on device/simulator
20+
- [ ] `API.md` updated if public exports changed
21+
22+
## Related
23+
24+
<!-- Linked issues or follow-ups. e.g. Closes #123 -->

‎.github/dependabot.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
version: 2
2+
updates:
3+
# Root package (library + workspaces)
4+
- package-ecosystem: npm
5+
directory: /
6+
schedule:
7+
interval: weekly
8+
day: monday
9+
open-pull-requests-limit: 5
10+
labels:
11+
- dependencies
12+
13+
# Expo example (standalone npm project)
14+
- package-ecosystem: npm
15+
directory: /examples/expo-example
16+
schedule:
17+
interval: weekly
18+
day: monday
19+
open-pull-requests-limit: 3
20+
labels:
21+
- dependencies
22+
23+
# GitHub Actions
24+
- package-ecosystem: github-actions
25+
directory: /
26+
schedule:
27+
interval: weekly
28+
day: monday
29+
open-pull-requests-limit: 5
30+
labels:
31+
- dependencies
32+
- ci

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ on:
33
push:
44
branches:
55
- master
6+
pull_request:
67
workflow_dispatch:
78

89
concurrency:

‎.github/workflows/claude-code-review.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: Claude Code Review
2+
3+
on:
4+
pull_request:
5+
types: [opened, synchronize]
6+
7+
permissions:
8+
contents: read
9+
pull-requests: write
10+
id-token: write
11+
12+
jobs:
13+
review:
14+
if: github.event.pull_request.user.login != 'dependabot[bot]'
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Checkout
18+
uses: actions/checkout@v4
19+
with:
20+
fetch-depth: 0
21+
22+
- name: Claude Code Review
23+
uses: anthropics/claude-code-action@beta
24+
with:
25+
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY_GITHUB_ACTIONS }}
26+
github_token: ${{ secrets.GITHUB_TOKEN }}
27+
direct_prompt: |
28+
Review this pull request. Focus on:
29+
- Correctness of the TypeScript API surface changes
30+
- Whether API.md is updated if src/index.tsx exports changed
31+
- Native layer consistency (android/ and ios/ should change together)
32+
- Conventional Commits format on the PR title
33+
- Any obvious bugs, type errors, or missing edge cases
34+
use_sticky_comment: true

‎.github/workflows/claude.yml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: Claude
2+
3+
on:
4+
issue_comment:
5+
types: [created]
6+
pull_request_review_comment:
7+
types: [created]
8+
issues:
9+
types: [opened]
10+
pull_request_review:
11+
types: [submitted]
12+
13+
permissions:
14+
contents: write
15+
pull-requests: write
16+
issues: write
17+
id-token: write
18+
19+
jobs:
20+
claude:
21+
if: |
22+
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
23+
(github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
24+
(github.event_name == 'issues' && contains(github.event.issue.body, '@claude')) ||
25+
(github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude'))
26+
runs-on: ubuntu-latest
27+
steps:
28+
- name: Checkout
29+
uses: actions/checkout@v4
30+
with:
31+
fetch-depth: 1
32+
33+
- name: Run Claude
34+
uses: anthropics/claude-code-action@beta
35+
with:
36+
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY_GITHUB_ACTIONS }}
37+
github_token: ${{ secrets.GITHUB_TOKEN }}

‎AGENTS.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# AGENTS.md
2+
3+
Single source of truth for agents working in this repo. `CLAUDE.md` imports this file via
4+
`@AGENTS.md`, so Claude Code, Codex, and any other agent that reads `AGENTS.md` share the same
5+
instructions.
6+
7+
---
8+
9+
## Behavioral Guidelines
10+
11+
Behavioral guidelines to reduce common LLM coding mistakes. (Adapted from Andrej Karpathy's
12+
[CLAUDE.md](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md).)
13+
14+
**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
15+
16+
### 1. Think Before Coding
17+
**Don't assume. Don't hide confusion. Surface tradeoffs.**
18+
- State your assumptions explicitly. If uncertain, ask.
19+
- If multiple interpretations exist, present them — don't pick silently.
20+
- If a simpler approach exists, say so. Push back when warranted.
21+
- If something is unclear, stop. Name what's confusing. Ask.
22+
23+
### 2. Simplicity First
24+
**Minimum code that solves the problem. Nothing speculative.**
25+
- No features beyond what was asked.
26+
- No abstractions for single-use code.
27+
- No "flexibility" or "configurability" that wasn't requested.
28+
- If you write 200 lines and it could be 50, rewrite it.
29+
30+
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
31+
32+
### 3. Surgical Changes
33+
**Touch only what you must. Clean up only your own mess.**
34+
- Don't "improve" adjacent code, comments, or formatting.
35+
- Don't refactor things that aren't broken.
36+
- Match existing style, even if you'd do it differently.
37+
- Remove imports/variables YOUR changes made unused; leave pre-existing dead code unless asked.
38+
39+
The test: every changed line should trace directly to the request.
40+
41+
### 4. Goal-Driven Execution
42+
**Define success criteria. Loop until verified.**
43+
- "Add validation" → "Write tests for invalid inputs, then make them pass."
44+
- "Fix the bug" → "Write a test that reproduces it, then make it pass."
45+
46+
For multi-step tasks, state a brief plan with a verify step for each item.
47+
48+
---
49+
50+
## Third-Party Library Docs
51+
52+
For **any third-party library**, use the **context7** MCP to fetch up-to-date documentation rather
53+
than relying on training data, which lags real library APIs. If the context7 MCP server is not
54+
available, set it up: https://context7.com/install
55+
56+
Key libraries in this repo to pull docs for: `react-native`, `react-native-builder-bob`, `turbo`,
57+
`@0xtrails/api`, `@0xtrails/wallet`, `0xtrails`.
58+
59+
---
60+
61+
## Project Overview
62+
63+
`@0xsequence/oms-react-native-sdk` is a React Native SDK (Turbo Module) for the OMS platform,
64+
bridging native iOS (Swift) and Android (Kotlin) SDKs to TypeScript. It exposes wallet auth (email
65+
OTP, OIDC redirect), transaction signing, balance queries, and session management to React Native
66+
and Expo apps.
67+
68+
## Repository Structure
69+
70+
- `src/` — TypeScript public API and native module bindings
71+
- `lib/` — built output (CommonJS, ESM, TypeScript declarations); generated by `yarn prepare`
72+
- `android/` — Kotlin native module
73+
- `ios/` — ObjC/Swift native module
74+
- `examples/sdk-example/` — React Native CLI example app
75+
- `examples/trails-actions-example/` — Trails demo with redirect auth
76+
- `examples/expo-example/` — standalone Expo example (not in Yarn workspace; uses `npm`)
77+
- `.github/workflows/` — CI (lint, typecheck, Android + iOS builds)
78+
79+
## Tech Stack
80+
81+
- **Language:** TypeScript (React Native Turbo Module; native layers in Kotlin + Objective-C/Swift)
82+
- **Package manager:** Yarn 4 (Berry) with workspaces; `examples/expo-example` uses `npm` standalone
83+
- **Build tool:** `react-native-builder-bob` + Turbo
84+
- **Linting:** ESLint 9 flat config + Prettier
85+
- **Node version:** v24.13.0 (see `.nvmrc`)
86+
87+
## Build & Run
88+
89+
```bash
90+
# Install dependencies
91+
yarn install
92+
93+
# Build the library
94+
yarn prepare
95+
96+
# Typecheck
97+
yarn typecheck
98+
99+
# Lint
100+
yarn lint
101+
102+
# Run SDK example (React Native CLI)
103+
yarn sdk-example start
104+
105+
# Run Expo example (standalone — uses npm, not yarn workspace)
106+
cd examples/expo-example && npm install && npm start
107+
```
108+
109+
## Testing
110+
111+
See **[TESTING.md](./TESTING.md)** for testing conventions, manual verification checklist, and the
112+
plan for when automated tests are added.
113+
114+
## Documentation
115+
116+
`API.md` at the repo root documents the full public TypeScript API for consumers.
117+
118+
## Conventions
119+
120+
- Commit messages and PR titles follow [Conventional Commits](https://www.conventionalcommits.org),
121+
e.g. `feat(auth): add OIDC refresh token support`.
122+
- The public API surface is documented in `API.md` — update it whenever `src/index.tsx` exports
123+
change.
124+
- The `lib/` directory is generated; never edit it by hand.
125+
- `examples/expo-example` is intentionally outside the Yarn workspace (`!examples/expo-example` in
126+
`package.json#workspaces`) — install its deps with `npm`, not `yarn`.
127+
- Native builds (Android/iOS) are slow; validate JS-layer changes with `yarn lint && yarn typecheck`
128+
first; leave full native builds to CI.
129+
- The `resolutions` block in `package.json` pins `0xtrails` / `@0xtrails/*` — update all three
130+
entries together when bumping the trails version.
131+
- Pre-release versions use the `0.x.y-alpha.N` scheme. Publishing steps are in `README.md`.
132+
133+
## CI/CD
134+
135+
Two workflows in `.github/workflows/`:
136+
- **`ci.yml`** — runs on pull requests, workflow dispatch, and pushes to `master`: lint, typecheck,
137+
library build, Android build, iOS build.
138+
- **`quick-checks.yml`** — runs on push to non-master branches: lint + typecheck only.
139+
140+
Pull requests run full CI, including native builds. If the native layer changed, make sure the
141+
Android and iOS PR checks pass before merging; validate locally when you need faster feedback.
142+
143+
## Common Pitfalls
144+
145+
- Running `yarn` inside `examples/expo-example` will fail — it's not a Yarn workspace member. Use
146+
`npm` there, or `yarn expo-example <script>` from the root.
147+
- `yarn prepare` regenerates `lib/` — if builds look stale, run `yarn clean && yarn prepare`.
148+
- The podspec resolves `oms-client-swift-sdk` and the Android module resolves
149+
`io.github.0xsequence:oms-client-kotlin-sdk` — bump native SDK versions in the podspec and
150+
`android/build.gradle` together.
151+
- Turbo cache can mask failures: if something seems wrong, run with `--force` to skip the cache.
152+
- Signed commits are required (enforced by branch protection) — configure `git commit -S` locally.
153+
154+
## Maintenance Matrix
155+
156+
| When this changes… | Also update… |
157+
|-------------------------------------------|-----------------------------------------------------------|
158+
| `src/index.tsx` exports | `API.md`, `lib/` (run `yarn prepare`) |
159+
| Native SDK version (Swift / Kotlin) | `OmsClientReactNativeSdk.podspec`, `android/build.gradle` |
160+
| `package.json` scripts or test commands | `TESTING.md`, `.github/workflows/ci.yml` |
161+
| Node version (`.nvmrc`) | `turbo.json#globalDependencies`, CI setup action |
162+
| `resolutions` (`0xtrails` / `@0xtrails/*`)| All three resolution entries together |
163+
| Repo structure (new top-level dirs) | `AGENTS.md` structure section |
164+
| Contributing workflow | `CONTRIBUTING.md`, `README.md` |

‎CHANGELOG.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Changelog
2+
3+
All notable changes to `@0xsequence/oms-react-native-sdk` are documented here.
4+
5+
Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
6+
Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
---
9+
10+
## [0.1.0-alpha.1] — 2025-05-27
11+
12+
### Added
13+
- Initial alpha release of `@0xsequence/oms-react-native-sdk` (renamed from `oms-client-react-native-sdk`).
14+
- TypeScript public API: `configure`, `startEmailAuth`, `completeEmailAuth`, `startOidcRedirectAuth`,
15+
`handleOidcRedirectCallback`, `getWalletAddress`, `signMessage`, `sendTransaction`,
16+
`getTokenBalances`, `formatUnits`, `parseUnits`.
17+
- React Native Turbo Module bridging iOS (Swift `oms-client-swift-sdk`) and Android (Kotlin
18+
`oms-client-kotlin-sdk`).
19+
- SDK example app, Trails actions demo (with redirect auth + pagination), and standalone Expo
20+
example.
21+
- GitHub Actions CI: lint, typecheck, Android build, iOS build.

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@AGENTS.md

‎CONTRIBUTING.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Contributing
2+
3+
## Prerequisites
4+
5+
- Node.js v24.13.0 (use `.nvmrc` — `nvm use` or `fnm use`)
6+
- Yarn 4 (`corepack enable` then `yarn --version`)
7+
- For Android builds: Android SDK, `ANDROID_HOME` set
8+
- For iOS builds: Xcode, CocoaPods, Ruby (`bundle install` inside the example)
9+
10+
## Setup
11+
12+
```bash
13+
git clone https://github.com/0xsequence/react-native-sdk.git
14+
cd react-native-sdk
15+
yarn install
16+
yarn prepare # build lib/
17+
```
18+
19+
## Repo structure
20+
21+
| Path | Purpose |
22+
|---|---|
23+
| `src/` | TypeScript public API and Turbo Module bindings |
24+
| `lib/` | Built output — generated, do not edit directly |
25+
| `android/` | Kotlin native module |
26+
| `ios/` | ObjC/Swift native module |
27+
| `examples/sdk-example/` | React Native CLI example (Yarn workspace) |
28+
| `examples/trails-actions-example/` | Trails demo (Yarn workspace) |
29+
| `examples/expo-example/` | Expo example — **not** a Yarn workspace; use `npm` here |
30+
31+
## Development workflow
32+
33+
```bash
34+
yarn lint # ESLint + Prettier check
35+
yarn typecheck # tsc
36+
yarn prepare # rebuild lib/ after src/ changes
37+
38+
# Run the SDK example
39+
yarn sdk-example start
40+
41+
# Run the Expo example (uses npm, not yarn)
42+
cd examples/expo-example && npm install && npm start
43+
```
44+
45+
## Before opening a PR
46+
47+
1. `yarn lint && yarn typecheck && yarn prepare` must pass cleanly.
48+
2. Update `API.md` if you changed public exports in `src/index.tsx`.
49+
3. Update `TESTING.md` if you added or changed test commands.
50+
4. If you changed the native layer (`android/`, `ios/`, `.podspec`), note it in the PR and make
51+
sure the Android and iOS CI checks pass before merging.
52+
5. PR title must follow [Conventional Commits](https://www.conventionalcommits.org), e.g. `fix(auth): handle expired OTP correctly`.
53+
54+
## Publishing (alpha)
55+
56+
Publishing steps are documented in `README.md` under the alpha publishing section. Only maintainers
57+
with npm publish access should publish.
58+
59+
## Signed commits
60+
61+
This repo requires signed commits. Configure `gpg` or SSH signing in your local git config before
62+
contributing.

0 commit comments

Comments
 (0)