From 5fc965ae52fc11c2f4741493dee3b9a04c8fd6b6 Mon Sep 17 00:00:00 2001
From: tsushanth <78000697+tsushanth@users.noreply.github.com>
Date: Thu, 11 Jun 2026 08:42:02 -0700
Subject: [PATCH] feat(package): expose subpath exports for lighter consumer
 imports
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #237.

The default `import { SquareClient } from 'square'` entry transitively
loads every API resource client, every Fern-generated type module, and
the ~1,300 runtime serialization schemas under `serialization/types/`.
On boot-sensitive workloads (serverless cold starts, autoscaling), the
total dominates startup time — the reporter measured ~600 ms just from
the require on an M3 MacBook Air, with `serialization/index.js` alone
accounting for 12 % of the boot path.

The SDK's surface is already split across small directories at the
package root after `prepack` copies `dist/.` over — `./api/`,
`./serialization/`, `./Client.js`, `./environments.js`, `./errors/` —
but the `exports` map only published `.` and `./legacy`, so consumers
who wanted to opt out couldn't reach the internal modules through a
supported path. Adding subpath entries (with `types` mappings so
TypeScript's nodenext / bundler resolvers find the declarations)
lets them import only the slice they need:

```ts
import type { Payment } from 'square/api/types/Payment';
import { PaymentsClient } from 'square/api/resources/payments';
import { Payment as PaymentSchema } from 'square/serialization/types/Payment';
import { SquareClient } from 'square/Client';
```

The default `import { SquareClient } from 'square'` entry is unchanged
and remains the recommended import for typical usage; the new entries
are strictly additive.

README gets a short subsection under "Usage" pointing at the new
import paths and the cold-start motivation.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md    | 26 ++++++++++++++++++++++++++
 package.json | 45 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+)

diff --git a/README.md b/README.md
index ae4ec5b2..80e18a19 100644
--- a/README.md
+++ b/README.md
@@ -76,6 +76,32 @@ await client.payments.create({
 });
 ```
 
+### Subpath imports
+
+For applications where startup latency matters (serverless cold starts, autoscaling
+boots, etc.), the SDK exposes its internal modules as package subpaths so consumers
+can avoid loading the full surface — including the ~1,300 runtime serialization
+schemas — when they only need a slice of it.
+
+```typescript
+// Just the type definitions for a single resource — no runtime schemas loaded.
+import type { Payment, Money } from "square/api/types/Payment";
+
+// Just one resource client.
+import { PaymentsClient } from "square/api/resources/payments";
+
+// Just the runtime serialization for a single model, e.g. for a custom worker
+// that needs to (de)serialize Square payloads without booting the client.
+import { Payment as PaymentSchema } from "square/serialization/types/Payment";
+
+// Just the SDK entry-point class and constants.
+import { SquareClient } from "square/Client";
+import { SquareEnvironment } from "square/environments";
+```
+
+The default `import { SquareClient } from "square"` entry continues to re-export the
+full surface and remains the recommended import for typical usage.
+
 ## Legacy SDK
 
 ## Legacy SDK
diff --git a/package.json b/package.json
index 483ff3dc..9fb7b5c0 100644
--- a/package.json
+++ b/package.json
@@ -69,6 +69,51 @@
     },
     "exports": {
         ".": "./index.js",
+        "./api": {
+            "types": "./api/index.d.ts",
+            "default": "./api/index.js"
+        },
+        "./api/resources/*": {
+            "types": "./api/resources/*/index.d.ts",
+            "default": "./api/resources/*/index.js"
+        },
+        "./api/types/*": {
+            "types": "./api/types/*.d.ts",
+            "default": "./api/types/*.js"
+        },
+        "./serialization": {
+            "types": "./serialization/index.d.ts",
+            "default": "./serialization/index.js"
+        },
+        "./serialization/resources/*": {
+            "types": "./serialization/resources/*/index.d.ts",
+            "default": "./serialization/resources/*/index.js"
+        },
+        "./serialization/types/*": {
+            "types": "./serialization/types/*.d.ts",
+            "default": "./serialization/types/*.js"
+        },
+        "./Client": {
+            "types": "./Client.d.ts",
+            "default": "./Client.js"
+        },
+        "./BaseClient": {
+            "types": "./BaseClient.d.ts",
+            "default": "./BaseClient.js"
+        },
+        "./environments": {
+            "types": "./environments.d.ts",
+            "default": "./environments.js"
+        },
+        "./errors": {
+            "types": "./errors/index.d.ts",
+            "default": "./errors/index.js"
+        },
+        "./version": {
+            "types": "./version.d.ts",
+            "default": "./version.js"
+        },
+        "./package.json": "./package.json",
         "./legacy": {
             "types": "./legacy/exports/index.d.ts",
             "require": {