Skip to content

Conversation

@sriramveeraghanta
Copy link
Member

@sriramveeraghanta sriramveeraghanta commented Oct 28, 2025

Summary by CodeRabbit

Release Notes

  • New Features

    • Introduced restructured SDK with centralized PlaneClient entry point for simplified API access
    • Added new API resources for Customers, Intake, and enhanced Work Items management
    • Expanded example scripts demonstrating end-to-end project setup
  • Chores

    • Enhanced build tooling with GitHub Actions workflows for automated testing and publishing
    • Updated development configuration with ESLint, Prettier, and Jest
    • Improved package metadata and distribution setup
  • Documentation

    • Comprehensive SDK documentation with quick-start guide and feature overview
    • Environment configuration templates for testing

@coderabbitai
Copy link

coderabbitai bot commented Oct 28, 2025

Caution

Review failed

The pull request is closed.

Walkthrough

This pull request performs a comprehensive migration from an OpenAPI-generated SDK to a custom, hand-built TypeScript SDK. The new architecture introduces a centralized PlaneClient entry point, a BaseResource abstraction for HTTP operations, custom API resource classes, and refactored models. The old generated code under .openapi-generator/ and src/apis/ is entirely removed and replaced with a modular, maintainable structure.

Changes

Cohort / File(s) Summary
Workflow & CI
.github/workflows/build-test.yaml, .github/workflows/publish-node-sdk.yml
Added GitHub Actions workflows for building, testing, and publishing the SDK using pnpm with Node.js setup and frozen lockfiles; added version extraction and GitHub release creation.
Configuration & Build
package.json, .gitignore, .npmignore, .prettierrc, .prettierignore, eslint.config.mjs, jest.config.js, tsconfig.jest.json
Updated package metadata (version 0.2.0, engines >=20.0.0), added Prettier configuration, refactored ESLint with plugin-based setup, added Jest configuration for test execution, expanded scripts for build/test/lint/format operations.
Documentation
README.md, AGENTS.MD, LICENSE, env.example, examples/README.md, examples/bootstrap-project.ts
Rewrote README with quick-start guide and feature list; added comprehensive SDK architecture documentation in AGENTS.MD; added MIT license; included example scripts and environment setup documentation.
Core SDK Architecture
src/Configuration.ts, src/api/BaseResource.ts, src/client/plane-client.ts, src/client/oauth-client.ts
Introduced centralized configuration management, abstract BaseResource for HTTP operations with logging and authentication support, PlaneClient as main SDK entry point, and OAuthClient for OAuth flows.
API Resources
src/api/Projects.ts, src/api/WorkItems/, src/api/Cycles.ts, src/api/Modules.ts, src/api/Labels.ts, src/api/States.ts, src/api/Users.ts, src/api/Members.ts, src/api/Pages.ts, src/api/Epics.ts, src/api/Intake.ts, src/api/Links.ts, src/api/Workspace.ts, src/api/Customers/, src/api/WorkItemTypes.ts, src/api/WorkItemProperties/
Implemented domain-specific API resource classes for each major entity (Projects, WorkItems, Cycles, etc.) with CRUD and list operations, each extending BaseResource and delegating HTTP operations.
Models & Types
src/models/
Added simplified, snake_case JSON-compatible model interfaces replacing auto-generated code; includes Cycle, WorkItem, Project, Label, State, Customer, Attachment, Comment, and supporting types.
Error Handling
src/errors/PlaneError.ts, src/errors/HttpError.ts, src/errors/index.ts
Introduced custom error hierarchy with PlaneError as base and HttpError for HTTP-specific failures, enabling status code and response tracking.
Public API Surface
src/index.ts, src/client/index.ts
Consolidated exports providing main SDK surface with PlaneClient, all API resources, models, and error classes; client index re-exports PlaneClient and OAuthClient.
Deleted Generated Code
.openapi-generator/FILES, .openapi-generator/VERSION, .openapi-generator-ignore, src/apis/*, old src/models/*
Removed entire OpenAPI-generated client including 20+ API classes, hundreds of model types, runtime utilities, and JSON serialization helpers; all replaced by custom implementations.

Sequence Diagram(s)

sequenceDiagram
    participant App as Application
    participant PC as PlaneClient
    participant Config as Configuration
    participant API as API Resource<br/>(e.g., Projects)
    participant BR as BaseResource
    participant HTTP as HTTP Client<br/>(axios)

    App->>PC: new PlaneClient({apiKey, baseUrl})
    PC->>Config: new Configuration(config)
    Config->>Config: validate()
    PC->>API: new Projects(config)
    
    App->>API: create(workspace, projectData)
    API->>BR: post('/projects', projectData)
    BR->>BR: buildUrl(endpoint)
    BR->>BR: getHeaders()
    BR->>HTTP: axios.post(url, data, {headers})
    HTTP-->>BR: response
    BR->>BR: handleError(response)
    BR-->>API: parsed response
    API-->>App: Promise<Project>
Loading
sequenceDiagram
    participant User as User
    participant OAuth as OAuthClient
    participant HTTP as HTTP Client<br/>(axios)
    participant API as Plane API

    User->>OAuth: new OAuthClient({clientId, clientSecret})
    User->>OAuth: exchangeCodeForToken(code)
    OAuth->>HTTP: axios.post(token_endpoint, {code, ...})
    HTTP->>API: POST /oauth/token
    API-->>HTTP: {access_token, refresh_token}
    HTTP-->>OAuth: response.data
    OAuth-->>User: PlaneOAuthTokenResponse
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Areas requiring extra attention:

  • BaseResource HTTP logic (src/api/BaseResource.ts): Verify Axios configuration, header construction (API key vs Bearer token), error handling strategy, and interceptor setup for logging
  • PlaneClient wiring (src/client/plane-client.ts): Ensure all API resources are correctly instantiated and configuration flows through the entire hierarchy
  • OAuthClient refactor (src/client/oauth-client.ts): Review shift from runtime-based to direct axios usage; verify token exchange and Basic auth implementation
  • API resource implementations (src/api/*.ts): Spot-check endpoint path construction, parameter handling, HTTP verb usage across diverse resources (Projects, WorkItems, Cycles, etc.)
  • Package.json and dependency graph: Verify axios version compatibility (1.12.2), ts-jest setup, and that pnpm workspaces/engines constraints are appropriate
  • Model structure changes: Confirm snake_case JSON field mapping and backward compatibility concerns if there are existing users of old models
  • Error handling hierarchy: Review PlaneError vs HttpError usage and status code propagation

Possibly related PRs

  • fix: eslint #12: Overlapping modifications to CI/CD workflows (.github/workflows/build-test.yaml) and configuration files (ESLint, .gitignore), suggesting related infrastructure/tooling updates.

Suggested reviewers

  • Prashant-Surya

Poem

🐰 The SDK awakens, no longer bound by OpenAPI chains,
A custom tapestry of resources, base classes, and domain reigns.
With PlaneClient as our compass and BaseResource at the core,
We hop toward a future where types and endpoints dance once more. 🎯

✨ Finishing touches
  • 📝 Generate docstrings
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch v0.2.x

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0f78686 and 885855d.

⛔ Files ignored due to path filters (2)
  • package-lock.json is excluded by !**/package-lock.json
  • pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
📒 Files selected for processing (107)
  • .github/workflows/build-test.yaml (1 hunks)
  • .github/workflows/publish-node-sdk.yml (1 hunks)
  • .gitignore (1 hunks)
  • .npmignore (0 hunks)
  • .openapi-generator-ignore (0 hunks)
  • .openapi-generator/FILES (0 hunks)
  • .openapi-generator/VERSION (0 hunks)
  • .prettierignore (1 hunks)
  • .prettierrc (1 hunks)
  • AGENTS.MD (1 hunks)
  • LICENSE (1 hunks)
  • README.md (1 hunks)
  • env.example (1 hunks)
  • eslint.config.mjs (1 hunks)
  • examples/README.md (1 hunks)
  • examples/bootstrap-project.ts (1 hunks)
  • jest.config.js (1 hunks)
  • package.json (1 hunks)
  • src/Configuration.ts (1 hunks)
  • src/api/BaseResource.ts (1 hunks)
  • src/api/Customers/Properties.ts (1 hunks)
  • src/api/Customers/Requests.ts (1 hunks)
  • src/api/Customers/index.ts (1 hunks)
  • src/api/Cycles.ts (1 hunks)
  • src/api/Epics.ts (1 hunks)
  • src/api/Intake.ts (1 hunks)
  • src/api/Labels.ts (1 hunks)
  • src/api/Links.ts (1 hunks)
  • src/api/Members.ts (1 hunks)
  • src/api/Modules.ts (1 hunks)
  • src/api/Pages.ts (1 hunks)
  • src/api/Projects.ts (1 hunks)
  • src/api/States.ts (1 hunks)
  • src/api/Users.ts (1 hunks)
  • src/api/WorkItemProperties/Options.ts (1 hunks)
  • src/api/WorkItemProperties/Values.ts (1 hunks)
  • src/api/WorkItemProperties/index.ts (1 hunks)
  • src/api/WorkItemTypes.ts (1 hunks)
  • src/api/WorkItems/Activities.ts (1 hunks)
  • src/api/WorkItems/Attachments.ts (1 hunks)
  • src/api/WorkItems/Comments.ts (1 hunks)
  • src/api/WorkItems/Relations.ts (1 hunks)
  • src/api/WorkItems/WorkLogs.ts (1 hunks)
  • src/api/WorkItems/index.ts (1 hunks)
  • src/api/Workspace.ts (1 hunks)
  • src/apis/AssetsApi.ts (0 hunks)
  • src/apis/CyclesApi.ts (0 hunks)
  • src/apis/EpicsApi.ts (0 hunks)
  • src/apis/IntakeApi.ts (0 hunks)
  • src/apis/LabelsApi.ts (0 hunks)
  • src/apis/MembersApi.ts (0 hunks)
  • src/apis/ModulesApi.ts (0 hunks)
  • src/apis/PagesApi.ts (0 hunks)
  • src/apis/ProjectsApi.ts (0 hunks)
  • src/apis/StatesApi.ts (0 hunks)
  • src/apis/UsersApi.ts (0 hunks)
  • src/apis/WorkItemActivityApi.ts (0 hunks)
  • src/apis/WorkItemAttachmentsApi.ts (0 hunks)
  • src/apis/WorkItemCommentsApi.ts (0 hunks)
  • src/apis/WorkItemLinksApi.ts (0 hunks)
  • src/apis/WorkItemPropertiesApi.ts (0 hunks)
  • src/apis/WorkItemTypesApi.ts (0 hunks)
  • src/apis/WorkItemWorklogsApi.ts (0 hunks)
  • src/apis/WorkItemsApi.ts (0 hunks)
  • src/apis/WorkspacesApi.ts (0 hunks)
  • src/apis/index.ts (0 hunks)
  • src/client/index.ts (1 hunks)
  • src/client/oauth-client.ts (5 hunks)
  • src/client/plane-client.ts (1 hunks)
  • src/errors/HttpError.ts (1 hunks)
  • src/errors/PlaneError.ts (1 hunks)
  • src/errors/index.ts (1 hunks)
  • src/index.ts (1 hunks)
  • src/models/AccessBd4Enum.ts (0 hunks)
  • src/models/Attachment.ts (1 hunks)
  • src/models/Comment.ts (1 hunks)
  • src/models/Customer.ts (1 hunks)
  • src/models/Cycle.ts (1 hunks)
  • src/models/CycleCreateRequest.ts (0 hunks)
  • src/models/CycleIssue.ts (0 hunks)
  • src/models/CycleIssueRequestRequest.ts (0 hunks)
  • src/models/CycleLite.ts (0 hunks)
  • src/models/EntityTypeEnum.ts (0 hunks)
  • src/models/Epic.ts (1 hunks)
  • src/models/GenericAssetUploadRequest.ts (0 hunks)
  • src/models/GetWorkspaceMembers200ResponseInner.ts (0 hunks)
  • src/models/GroupEnum.ts (0 hunks)
  • src/models/Intake.ts (1 hunks)
  • src/models/IntakeIssue.ts (0 hunks)
  • src/models/IntakeIssueCreateRequest.ts (0 hunks)
  • src/models/IntakeWorkItemStatusEnum.ts (0 hunks)
  • src/models/Issue.ts (0 hunks)
  • src/models/IssueActivity.ts (0 hunks)
  • src/models/IssueAttachment.ts (0 hunks)
  • src/models/IssueAttachmentUploadRequest.ts (0 hunks)
  • src/models/IssueComment.ts (0 hunks)
  • src/models/IssueCommentCreateRequest.ts (0 hunks)
  • src/models/IssueDetail.ts (0 hunks)
  • src/models/IssueExpand.ts (0 hunks)
  • src/models/IssueForIntakeRequest.ts (0 hunks)
  • src/models/IssueLink.ts (0 hunks)
  • src/models/IssueLinkCreateRequest.ts (0 hunks)
  • src/models/IssuePropertyAPI.ts (0 hunks)
  • src/models/IssuePropertyAPIRelationTypeEnum.ts (0 hunks)
  • src/models/IssuePropertyAPIRequest.ts (0 hunks)
  • src/models/IssuePropertyOptionAPI.ts (0 hunks)
  • src/models/IssuePropertyOptionAPIRequest.ts (0 hunks)

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

sriramveeraghanta and others added 5 commits October 28, 2025 18:56
* feat!: add handcrafted SDK v0.2.0

- added models for each entities
- added APIs for all available Plane entities
- tests to verify e2e api sanity
- examples for reference

BREAKING CHANGE: must be carefully upgraded from 0.1.x versions as method signatures
are changed

* chore: adding prettier config

* chore: remove ds store

* fix: format all files

* chore: package imports

---------

Co-authored-by: Surya Prashanth <[email protected]>
* move existing tests under unit folder

* don't fail unit tests when env is not setup

* create helpers folder for test helpers

* feat: add e2e test to verify project use case

* add jest and tsconfig.jest files

* feat: add unit tests using jest for all entities
* chore: eslint config setup

* chore: updated the build test workflow

* chore: setup pnpm workflow

* chore: build errors

* chore: updated the push step
* ops: update publishing flow for nw sdk

* run only e2e tests in github actions
@sriramveeraghanta sriramveeraghanta marked this pull request as ready for review October 29, 2025 14:19
@sriramveeraghanta sriramveeraghanta merged commit 2d03c00 into main Oct 29, 2025
0 of 2 checks passed
@sriramveeraghanta sriramveeraghanta deleted the v0.2.x branch October 29, 2025 14:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants