feat: implement TypeScript Connect API client by zackverham · Pull Request #3673 · posit-dev/publisher

zackverham · 2026-03-09T19:36:22Z

Intent

Implement a TypeScript Connect API client package (@posit-dev/connect-api) and validate it against contract tests alongside the existing Go backend.

Type of Change

New Feature
Refactoring

Approach

Created a standalone packages/connect-api/ package with a ConnectAPI class that wraps the Posit Connect REST API. All 15 API methods are implemented:

Auth & User: TestAuthentication, GetCurrentUser
Content CRUD: ContentDetails, CreateDeployment, UpdateDeployment
Environment: GetEnvVars, SetEnvVars
Bundles: UploadBundle, LatestBundleID, DownloadBundle
Deployment: DeployBundle, WaitForTask, ValidateDeployment
Server Info: GetIntegrations, GetSettings

Key design decisions:

axios for HTTP — uses axios.create() with a pre-configured baseURL, default Authorization header, and validateStatus: () => true so the client controls error handling rather than axios auto-throwing on non-2xx
Raw API responses — every method returns the exact JSON the Connect API sends back (full DTOs), rather than constructing new objects or extracting single fields. The contract test adapter handles any field extraction needed.
Branded ID types (ContentID, BundleID, TaskID) for type safety on parameters

User Impact

None — this is preparatory code.

Automated Tests

52 unit tests in packages/connect-api/ (vitest) covering all methods, error paths, and URL construction
All 68 contract tests pass with both backends (npx vitest run and API_BACKEND=typescript npx vitest run)
CI runs contract tests against both Go and TypeScript backends

🤖 Generated with Claude Code

Replace the stub TypeScriptDirectClient with a full implementation that makes HTTP requests directly to the Connect server, mirroring the Go client's behavior. All 15 API methods are implemented and pass the same 68 contract tests that validate the Go client. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Move the TypeScript Connect API client from the contract test file into a standalone @posit-dev/connect-client package with proper types, error classes, and barrel exports. The contract test adapter becomes a thin wrapper that imports from the new package. All 68 contract tests pass with both Go and TypeScript backends. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add a matrix strategy to the contract-tests job so it runs once with API_BACKEND=go (existing behavior) and once with API_BACKEND=typescript (new ConnectClient from @posit-dev/connect-client). The TypeScript backend skips Go setup since it doesn't need the harness binary. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

dotNomad · 2026-03-09T22:01:48Z

test/connect-api-contracts/package.json

+  "dependencies": {
+    "@posit-dev/connect-client": "file:../../packages/connect-client"
+  },


If we continue down this path (which I think we should) we should consider doing a few things:

create a shared tsconfig by creating a TypeScript configuration package. The Turborepo docs have some ideas on how to do this. This will prevent us from duplicating tsconfig.json setups everywhere.

We actually have an old issue for this: Setup shared TypeScript configurations for monorepo packages #1295

we should also consider using npm workspaces: Setup npm workspaces for shared code #1291

We can wait until we ditch Go, and can raise the extension to the top level of the repo

I think its a good idea to have separate packages. It makes the way we import and deal with some of the code around the homeView much easier to deal with. Right now it imports types from extension/vscode by importing with ../../.. which is not great.

@dotNomad would you say creating a shared configuration package should be part of this PR, or part of follow-up work?

dotNomad · 2026-03-09T22:08:59Z

packages/connect-api/src/client.ts

+  // HTTP helpers
+  // ---------------------------------------------------------------------------
+
+  private async request(


I would prefer to keep using axios despite some of the problems we've had so we don't have to write our own error handling logic, or change how we do it in a lot of spots. That would simplify what we have here quite a bit.

dotNomad · 2026-03-09T22:12:39Z

packages/connect-api/src/client.ts

+    return {
+      id: dto.guid,
+      username: dto.username,
+      first_name: dto.first_name,
+      last_name: dto.last_name,
+      email: dto.email,
+    };


This is a preference in design, but in my opinion it has a lot of benefits:

I would prefer to return the exact thing the API call responds with, including all data, and not creating new objects.

This will keep this code extremely single use and the only thing we will need to adjust overtime are the types. We won't have to adjust the functions since they just pass the response right through. We can always extract the data from the response.

It is much more flexible.

You can read more in our README.md for the Go API client we wrote: https://github.com/posit-dev/publisher/blob/183abd7d744fb8f6d8bcffc323717547521eca57/extensions/vscode/src/api/README.md

I see this is mapping a UserDTO to a User, but I think we should avoid this. It would make the initial migration easier, but once it is complete it will be much more difficult to understand why the attributes are different.

Down to discuss temporary trade-offs.

dotNomad · 2026-03-09T22:15:03Z

packages/connect-api/src/types.ts

+export type ContentID = string & { readonly __brand: "ContentID" };
+export type BundleID = string & { readonly __brand: "BundleID" };
+export type TaskID = string & { readonly __brand: "TaskID" };
+export type UserID = string & { readonly __brand: "UserID" };
+export type GUID = string & { readonly __brand: "GUID" };


Branded Types are a nice addition to avoid ID overlap 👍

Rename the package from @posit-dev/connect-client to @posit-dev/connect-api and add comprehensive unit tests for the ConnectClient class and error types. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Also renames ConnectClientOptions to ConnectAPIOptions and ConnectClientError to ConnectAPIError for consistency. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace native fetch with axios for HTTP requests in the ConnectAPI class. Uses axios.create() with baseURL, default Authorization header, and validateStatus: () => true to preserve existing error handling. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Stop constructing new objects in client methods — return the exact response data from the Connect API instead. Removes the User type (a client-side invention) and updates the contract test adapter to extract fields from full DTOs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

zackverham · 2026-03-10T13:55:10Z

test/connect-api-contracts/src/clients/ts-direct-client.ts

+    };
+  }
+
+  private async dispatch(


once we get rid of the go API client, we can clean up the shape of this stub, or just use the ConnectAPI client directly in test.

Right now the test shape is coupled to the go client's shape so we can have an apples-to-apples comparison in the contract tests, but we won't always need to have the apples-to-apples comparison we're running here.

zackverham · 2026-03-10T18:14:41Z

packages/connect-api/src/client.test.ts

+});
+
+// ---------------------------------------------------------------------------
+// getSettings


I could be convinced that the right approach will end up being splitting these out into atomic calls - maybe something we can feel out as we go along.

zackverham · 2026-03-10T18:15:46Z

packages/connect-api/src/client.ts

+   * Validates credentials and checks user state (locked, confirmed, role).
+   * Returns the full UserDTO on success; throws AuthenticationError otherwise.
+   */
+  async testAuthentication(): Promise<UserDTO> {


not strictly a light wrapper around an API call, but this does seem pretty useful to have on the API client.

zackverham · 2026-03-10T18:18:41Z

packages/connect-api/src/client.ts

+
+  /**
+   * Fetches composite server settings from 7 separate endpoints,
+   * mirroring the Go client's GetSettings behavior.


Flagging again - not sure if we want to mimic this or not

zackverham · 2026-03-10T18:19:33Z

packages/connect-api/src/types.ts

+// Integration type
+// ---------------------------------------------------------------------------
+
+export interface Integration {


@dotNomad is there any convention around calling something vs DTO?

zackverham and others added 4 commits March 9, 2026 15:35

style: fix prettier formatting in client files

e0295aa

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

dotNomad reviewed Mar 9, 2026

View reviewed changes

zackverham changed the title ~~feat: implement TypeScript Connect API client for contract tests~~ feat: implement TypeScript Connect API client Mar 10, 2026

zackverham and others added 4 commits March 10, 2026 08:51

feat: rename connect-client to connect-api and add unit tests

7c80a3b

Rename the package from @posit-dev/connect-client to @posit-dev/connect-api and add comprehensive unit tests for the ConnectClient class and error types. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

refactor: rename ConnectClient class to ConnectAPI

fbf75d2

Also renames ConnectClientOptions to ConnectAPIOptions and ConnectClientError to ConnectAPIError for consistency. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

zackverham commented Mar 10, 2026

View reviewed changes

zackverham mentioned this pull request Mar 10, 2026

Implement ConnectAPI client in typescript #3680

Open

zackverham commented Mar 10, 2026

View reviewed changes

zackverham marked this pull request as ready for review March 10, 2026 18:19

zackverham requested a review from a team as a code owner March 10, 2026 18:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: implement TypeScript Connect API client#3673

feat: implement TypeScript Connect API client#3673
zackverham wants to merge 8 commits intomainfrom
ts-connect-client

zackverham commented Mar 9, 2026 •

edited

Loading

Uh oh!

dotNomad Mar 9, 2026

Uh oh!

zackverham Mar 10, 2026

Uh oh!

dotNomad Mar 9, 2026

Uh oh!

dotNomad Mar 9, 2026

Uh oh!

dotNomad Mar 9, 2026

Uh oh!

dotNomad Mar 9, 2026

Uh oh!

zackverham Mar 10, 2026

Uh oh!

zackverham Mar 10, 2026

Uh oh!

zackverham Mar 10, 2026

Uh oh!

zackverham Mar 10, 2026

Uh oh!

zackverham Mar 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

zackverham commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Intent

Type of Change

Approach

User Impact

Automated Tests

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

zackverham commented Mar 9, 2026 •

edited

Loading