Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: update SDK settings #3

Merged
merged 1 commit into from
Oct 31, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,12 +55,12 @@ $ cd sent-node
# With yarn
$ yarn link
$ cd ../my-package
$ yarn link sent
$ yarn link @sent/node

# With pnpm
$ pnpm link --global
$ cd ../my-package
$ pnpm link -—global sent
$ pnpm link -—global @sent/node
```

## Running tests
Expand Down
19 changes: 8 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Sent Node API Library

[![NPM version](https://img.shields.io/npm/v/sent.svg)](https://npmjs.org/package/sent) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/sent)
[![NPM version](https://img.shields.io/npm/v/@sent/node.svg)](https://npmjs.org/package/@sent/node) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@sent/node)

This library provides convenient access to the Sent REST API from server-side TypeScript or JavaScript.

Expand All @@ -11,19 +11,16 @@ It is generated with [Stainless](https://www.stainlessapi.com/).
## Installation

```sh
npm install git+ssh://git@github.com:sentdm/sent-node.git
npm install @sent/node
```

> [!NOTE]
> Once this package is [published to npm](https://app.stainlessapi.com/docs/guides/publish), this will become: `npm install sent`

## Usage

The full API of this library can be found in [api.md](api.md).

<!-- prettier-ignore -->
```js
import Sent from 'sent';
import Sent from '@sent/node';

const client = new Sent();

Expand All @@ -40,7 +37,7 @@ This library includes TypeScript definitions for all request params and response

<!-- prettier-ignore -->
```ts
import Sent from 'sent';
import Sent from '@sent/node';

const client = new Sent();

Expand Down Expand Up @@ -207,11 +204,11 @@ add the following import before your first import `from "Sent"`:
```ts
// Tell TypeScript and the package to use the global web fetch instead of node-fetch.
// Note, despite the name, this does not add any polyfills, but expects them to be provided if needed.
import 'sent/shims/web';
import Sent from 'sent';
import '@sent/node/shims/web';
import Sent from '@sent/node';
```

To do the inverse, add `import "sent/shims/node"` (which does import polyfills).
To do the inverse, add `import "@sent/node/shims/node"` (which does import polyfills).
This can also be useful if you are getting the wrong TypeScript types for `Response` ([more details](https://github.com/sentdm/sent-node/tree/main/src/_shims#readme)).

### Logging and middleware
Expand All @@ -221,7 +218,7 @@ which can be used to inspect or alter the `Request` or `Response` before/after e

```ts
import { fetch } from 'undici'; // as one example
import Sent from 'sent';
import Sent from '@sent/node';

const client = new Sent({
fetch: async (url: RequestInfo, init?: RequestInit): Promise<Response> => {
Expand Down
6 changes: 3 additions & 3 deletions jest.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@ const config: JestConfigWithTsJest = {
'^.+\\.(t|j)sx?$': ['@swc/jest', { sourceMaps: 'inline' }],
},
moduleNameMapper: {
'^sent$': '<rootDir>/src/index.ts',
'^sent/_shims/auto/(.*)$': '<rootDir>/src/_shims/auto/$1-node',
'^sent/(.*)$': '<rootDir>/src/$1',
'^@sent/node$': '<rootDir>/src/index.ts',
'^@sent/node/_shims/auto/(.*)$': '<rootDir>/src/_shims/auto/$1-node',
'^@sent/node/(.*)$': '<rootDir>/src/$1',
},
modulePathIgnorePatterns: [
'<rootDir>/ecosystem-tests/',
Expand Down
6 changes: 3 additions & 3 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"name": "sent",
"name": "@sent/node",
"version": "0.0.1-alpha.0",
"description": "The official TypeScript library for the Sent API",
"author": "Sent <team@sent.dm>",
Expand Down Expand Up @@ -60,8 +60,8 @@
"./shims/web.mjs"
],
"imports": {
"sent": ".",
"sent/*": "./src/*"
"@sent/node": ".",
"@sent/node/*": "./src/*"
},
"exports": {
"./_shims/auto/*": {
Expand Down
6 changes: 3 additions & 3 deletions scripts/build
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ node scripts/utils/check-version.cjs

# Build into dist and will publish the package from there,
# so that src/resources/foo.ts becomes <package root>/resources/foo.js
# This way importing from `"sent/resources/foo"` works
# This way importing from `"@sent/node/resources/foo"` works
# even with `"moduleResolution": "node"`

rm -rf dist; mkdir dist
Expand Down Expand Up @@ -47,8 +47,8 @@ node scripts/utils/postprocess-files.cjs

# make sure that nothing crashes when we require the output CJS or
# import the output ESM
(cd dist && node -e 'require("sent")')
(cd dist && node -e 'import("sent")' --input-type=module)
(cd dist && node -e 'require("@sent/node")')
(cd dist && node -e 'import("@sent/node")' --input-type=module)

if command -v deno &> /dev/null && [ -e ./scripts/build-deno ]
then
Expand Down
4 changes: 2 additions & 2 deletions scripts/utils/postprocess-files.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ const fs = require('fs');
const path = require('path');
const { parse } = require('@typescript-eslint/parser');

const pkgImportPath = process.env['PKG_IMPORT_PATH'] ?? 'sent/';
const pkgImportPath = process.env['PKG_IMPORT_PATH'] ?? '@sent/node/';

const distDir =
process.env['DIST_PATH'] ?
Expand Down Expand Up @@ -142,7 +142,7 @@ async function postprocess() {

if (file.endsWith('.d.ts')) {
// work around bad tsc behavior
// if we have `import { type Readable } from 'sent/_shims/index'`,
// if we have `import { type Readable } from '@sent/node/_shims/index'`,
// tsc sometimes replaces `Readable` with `import("stream").Readable` inline
// in the output .d.ts
transformed = transformed.replace(/import\("stream"\).Readable/g, 'Readable');
Expand Down
32 changes: 16 additions & 16 deletions src/_shims/README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# 👋 Wondering what everything in here does?

`sent` supports a wide variety of runtime environments like Node.js, Deno, Bun, browsers, and various
`@sent/node` supports a wide variety of runtime environments like Node.js, Deno, Bun, browsers, and various
edge runtimes, as well as both CommonJS (CJS) and EcmaScript Modules (ESM).

To do this, `sent` provides shims for either using `node-fetch` when in Node (because `fetch` is still experimental there) or the global `fetch` API built into the environment when not in Node.
To do this, `@sent/node` provides shims for either using `node-fetch` when in Node (because `fetch` is still experimental there) or the global `fetch` API built into the environment when not in Node.

It uses [conditional exports](https://nodejs.org/api/packages.html#conditional-exports) to
automatically select the correct shims for each environment. However, conditional exports are a fairly new
Expand All @@ -15,32 +15,32 @@ getting the wrong raw `Response` type from `.asResponse()`, for example.

The user can work around these issues by manually importing one of:

- `import 'sent/shims/node'`
- `import 'sent/shims/web'`
- `import '@sent/node/shims/node'`
- `import '@sent/node/shims/web'`

All of the code here in `_shims` handles selecting the automatic default shims or manual overrides.

### How it works - Runtime

Runtime shims get installed by calling `setShims` exported by `sent/_shims/registry`.
Runtime shims get installed by calling `setShims` exported by `@sent/node/_shims/registry`.

Manually importing `sent/shims/node` or `sent/shims/web`, calls `setShims` with the respective runtime shims.
Manually importing `@sent/node/shims/node` or `@sent/node/shims/web`, calls `setShims` with the respective runtime shims.

All client code imports shims from `sent/_shims/index`, which:
All client code imports shims from `@sent/node/_shims/index`, which:

- checks if shims have been set manually
- if not, calls `setShims` with the shims from `sent/_shims/auto/runtime`
- re-exports the installed shims from `sent/_shims/registry`.
- if not, calls `setShims` with the shims from `@sent/node/_shims/auto/runtime`
- re-exports the installed shims from `@sent/node/_shims/registry`.

`sent/_shims/auto/runtime` exports web runtime shims.
If the `node` export condition is set, the export map replaces it with `sent/_shims/auto/runtime-node`.
`@sent/node/_shims/auto/runtime` exports web runtime shims.
If the `node` export condition is set, the export map replaces it with `@sent/node/_shims/auto/runtime-node`.

### How it works - Type time

All client code imports shim types from `sent/_shims/index`, which selects the manual types from `sent/_shims/manual-types` if they have been declared, otherwise it exports the auto types from `sent/_shims/auto/types`.
All client code imports shim types from `@sent/node/_shims/index`, which selects the manual types from `@sent/node/_shims/manual-types` if they have been declared, otherwise it exports the auto types from `@sent/node/_shims/auto/types`.

`sent/_shims/manual-types` exports an empty namespace.
Manually importing `sent/shims/node` or `sent/shims/web` merges declarations into this empty namespace, so they get picked up by `sent/_shims/index`.
`@sent/node/_shims/manual-types` exports an empty namespace.
Manually importing `@sent/node/shims/node` or `@sent/node/shims/web` merges declarations into this empty namespace, so they get picked up by `@sent/node/_shims/index`.

`sent/_shims/auto/types` exports web type definitions.
If the `node` export condition is set, the export map replaces it with `sent/_shims/auto/types-node`, though TS only picks this up if `"moduleResolution": "nodenext"` or `"moduleResolution": "bundler"`.
`@sent/node/_shims/auto/types` exports web type definitions.
If the `node` export condition is set, the export map replaces it with `@sent/node/_shims/auto/types-node`, though TS only picks this up if `"moduleResolution": "nodenext"` or `"moduleResolution": "bundler"`.
2 changes: 1 addition & 1 deletion src/_shims/index.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
* Disclaimer: modules in _shims aren't intended to be imported by SDK users.
*/
import { manual } from './manual-types';
import * as auto from 'sent/_shims/auto/types';
import * as auto from '@sent/node/_shims/auto/types';
import { type RequestOptions } from '../core';

type SelectType<Manual, Auto> = unknown extends Manual ? Auto : Manual;
Expand Down
2 changes: 1 addition & 1 deletion src/_shims/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
* Disclaimer: modules in _shims aren't intended to be imported by SDK users.
*/
const shims = require('./registry');
const auto = require('sent/_shims/auto/runtime');
const auto = require('@sent/node/_shims/auto/runtime');
if (!shims.kind) shims.setShims(auto.getRuntime(), { auto: true });
for (const property of Object.keys(shims)) {
Object.defineProperty(exports, property, {
Expand Down
2 changes: 1 addition & 1 deletion src/_shims/index.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,6 @@
* Disclaimer: modules in _shims aren't intended to be imported by SDK users.
*/
import * as shims from './registry.mjs';
import * as auto from 'sent/_shims/auto/runtime';
import * as auto from '@sent/node/_shims/auto/runtime';
if (!shims.kind) shims.setShims(auto.getRuntime(), { auto: true });
export * from './registry.mjs';
4 changes: 2 additions & 2 deletions src/_shims/manual-types.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@
/**
* Types will get added to this namespace when you import one of the following:
*
* import 'sent/shims/node'
* import 'sent/shims/web'
* import '@sent/node/shims/node'
* import '@sent/node/shims/web'
*
* Importing more than one will cause type and runtime errors.
*/
Expand Down
6 changes: 4 additions & 2 deletions src/_shims/registry.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,11 +42,13 @@ export let isFsReadStream: Shims['isFsReadStream'] | undefined = undefined;
export function setShims(shims: Shims, options: { auto: boolean } = { auto: false }) {
if (auto) {
throw new Error(
`you must \`import 'sent/shims/${shims.kind}'\` before importing anything else from sent`,
`you must \`import '@sent/node/shims/${shims.kind}'\` before importing anything else from @sent/node`,
);
}
if (kind) {
throw new Error(`can't \`import 'sent/shims/${shims.kind}'\` after \`import 'sent/shims/${kind}'\``);
throw new Error(
`can't \`import '@sent/node/shims/${shims.kind}'\` after \`import '@sent/node/shims/${kind}'\``,
);
}
auto = options.auto;
kind = shims.kind;
Expand Down
6 changes: 3 additions & 3 deletions src/_shims/web-runtime.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ export function getRuntime({ manuallyImported }: { manuallyImported?: boolean }
const recommendation =
manuallyImported ?
`You may need to use polyfills`
: `Add one of these imports before your first \`import … from 'sent'\`:
- \`import 'sent/shims/node'\` (if you're running on Node)
- \`import 'sent/shims/web'\` (otherwise)
: `Add one of these imports before your first \`import … from '@sent/node'\`:
- \`import '@sent/node/shims/node'\` (if you're running on Node)
- \`import '@sent/node/shims/web'\` (otherwise)
`;

let _fetch, _Request, _Response, _Headers;
Expand Down
12 changes: 6 additions & 6 deletions src/core.ts
Original file line number Diff line number Diff line change
Expand Up @@ -99,9 +99,9 @@ export class APIPromise<T> extends Promise<T> {
*
* 👋 Getting the wrong TypeScript type for `Response`?
* Try setting `"moduleResolution": "NodeNext"` if you can,
* or add one of these imports before your first `import … from 'sent'`:
* - `import 'sent/shims/node'` (if you're running on Node)
* - `import 'sent/shims/web'` (otherwise)
* or add one of these imports before your first `import … from '@sent/node'`:
* - `import '@sent/node/shims/node'` (if you're running on Node)
* - `import '@sent/node/shims/web'` (otherwise)
*/
asResponse(): Promise<Response> {
return this.responsePromise.then((p) => p.response);
Expand All @@ -115,9 +115,9 @@ export class APIPromise<T> extends Promise<T> {
*
* 👋 Getting the wrong TypeScript type for `Response`?
* Try setting `"moduleResolution": "NodeNext"` if you can,
* or add one of these imports before your first `import … from 'sent'`:
* - `import 'sent/shims/node'` (if you're running on Node)
* - `import 'sent/shims/web'` (otherwise)
* or add one of these imports before your first `import … from '@sent/node'`:
* - `import '@sent/node/shims/node'` (if you're running on Node)
* - `import '@sent/node/shims/web'` (otherwise)
*/
async withResponse(): Promise<{ data: T; response: Response }> {
const [data, response] = await Promise.all([this.parse(), this.asResponse()]);
Expand Down
2 changes: 1 addition & 1 deletion tests/api-resources/contacts/contacts.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import Sent from 'sent';
import Sent from '@sent/node';
import { Response } from 'node-fetch';

const client = new Sent({
Expand Down
2 changes: 1 addition & 1 deletion tests/api-resources/contacts/id.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import Sent from 'sent';
import Sent from '@sent/node';
import { Response } from 'node-fetch';

const client = new Sent({
Expand Down
2 changes: 1 addition & 1 deletion tests/api-resources/contacts/phone.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import Sent from 'sent';
import Sent from '@sent/node';
import { Response } from 'node-fetch';

const client = new Sent({
Expand Down
2 changes: 1 addition & 1 deletion tests/api-resources/customers.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import Sent from 'sent';
import Sent from '@sent/node';
import { Response } from 'node-fetch';

const client = new Sent({
Expand Down
2 changes: 1 addition & 1 deletion tests/api-resources/messages.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import Sent from 'sent';
import Sent from '@sent/node';
import { Response } from 'node-fetch';

const client = new Sent({
Expand Down
2 changes: 1 addition & 1 deletion tests/api-resources/sms.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import Sent from 'sent';
import Sent from '@sent/node';
import { Response } from 'node-fetch';

const client = new Sent({
Expand Down
2 changes: 1 addition & 1 deletion tests/api-resources/templates.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import Sent from 'sent';
import Sent from '@sent/node';
import { Response } from 'node-fetch';

const client = new Sent({
Expand Down
2 changes: 1 addition & 1 deletion tests/api-resources/whatsapp.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import Sent from 'sent';
import Sent from '@sent/node';
import { Response } from 'node-fetch';

const client = new Sent({
Expand Down
6 changes: 3 additions & 3 deletions tests/form.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { multipartFormRequestOptions, createForm } from 'sent/core';
import { Blob } from 'sent/_shims/index';
import { toFile } from 'sent';
import { multipartFormRequestOptions, createForm } from '@sent/node/core';
import { Blob } from '@sent/node/_shims/index';
import { toFile } from '@sent/node';

describe('form data validation', () => {
test('valid values do not error', async () => {
Expand Down
6 changes: 3 additions & 3 deletions tests/index.test.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import Sent from 'sent';
import { APIUserAbortError } from 'sent';
import { Headers } from 'sent/core';
import Sent from '@sent/node';
import { APIUserAbortError } from '@sent/node';
import { Headers } from '@sent/node/core';
import defaultFetch, { Response, type RequestInit, type RequestInfo } from 'node-fetch';

describe('instantiate client', () => {
Expand Down
4 changes: 2 additions & 2 deletions tests/responses.test.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { createResponseHeaders } from 'sent/core';
import { Headers } from 'sent/_shims/index';
import { createResponseHeaders } from '@sent/node/core';
import { Headers } from '@sent/node/_shims/index';

describe('response parsing', () => {
// TODO: test unicode characters
Expand Down
2 changes: 1 addition & 1 deletion tests/stringifyQuery.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { Sent } from 'sent';
import { Sent } from '@sent/node';

const { stringifyQuery } = Sent.prototype as any;

Expand Down
Loading