netlify-api 1.4.0 → 3.0.4

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) SferaDev
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -32,20 +32,59 @@ Operations are grouped by tag: `client.api.<tag>.<operation>(params)`.
 ```ts
 const client = new NetlifyApi({
   token: process.env.NETLIFY_TOKEN ?? "",
-  basePath: "https://api.netlify.com/api/v1", // optional override
+  basePath: "/api/v1", // optional, the default
   fetch: myFetchImplementation, // optional
 });
 ```
 
+`basePath` is the path prefix appended to `https://api.netlify.com`, not a full URL. The host is fixed and cannot be configured.
+
+### Calling by method and path
+
+`client.request()` addresses an operation by its HTTP method and path instead of its tag and name. Parameters and the result are typed the same way as through `client.api`.
+
+```ts
+const sites = await client.request("GET /sites", { queryParams: { per_page: 10 } });
+```
+
+An endpoint that is not in the spec throws.
+
+### Refreshing an OAuth token
+
+```ts
+const { tokenType, accessToken, refreshToken, scope, createdAt } = await client.auth.refreshToken({
+  refreshToken: storedRefreshToken,
+  clientId: process.env.NETLIFY_CLIENT_ID ?? "",
+  clientSecret: process.env.NETLIFY_CLIENT_SECRET ?? "",
+  authToken: currentAccessToken, // optional, defaults to the client's token
+});
+```
+
+This posts to `https://api.netlify.com/oauth/token` and returns the new token pair, with `createdAt` as a Unix timestamp.
+
+### Errors
+
+A request that gets an HTTP error response rejects with `{ status, payload }`: `status` is the HTTP status code and `payload` is the parsed error body, or the raw body text, up to 1000 characters, when it is not JSON. A request that never gets a response rejects with an `Error` whose message names the method, the path and the reason, and whose `cause` is the original exception. A request cancelled through `signal` rejects with what the signal was aborted with, as is: the `AbortError`, or the `TimeoutError` of `AbortSignal.timeout()`.
+
+```ts
+try {
+  await client.api.site.getSite({ pathParams: { site_id: "missing" } });
+} catch (error) {
+  if (typeof error === "object" && error !== null && "status" in error && "payload" in error) {
+    console.error(error.status, error.payload);
+  }
+}
+```
+
 ## Effect
 
-The `effect` entrypoint exposes every operation as an `Effect`. It requires `effect` as a peer dependency.
+The `effect` entrypoint exposes every operation as an `Effect`. It requires `effect` 4 as a peer dependency.
 
 ```ts
 import { Effect } from "effect";
 import { ApiService, makeApiLayer } from "netlify-api/effect";
 
-const program = ApiService.site.listSites({});
+const program = ApiService.site.listSites();
 
 await Effect.runPromise(
   program.pipe(Effect.provide(makeApiLayer({ token: process.env.NETLIFY_TOKEN })))
@@ -54,6 +93,8 @@ await Effect.runPromise(
 
 Errors are typed as `ApiError`, `NetworkError` and `ValidationError`.
 
+`makeApiLayer` accepts `token` and `headers`. Its `baseUrl` option is ignored by this client, which always calls `https://api.netlify.com/api/v1`.
+
 ## Entrypoints
 
 | Import | Contents |