@vantage-sh/vantage-client 0.1.0-beta7 → 2.0.0

package/README.md

@@ -1,118 +1,239 @@
-[![Build Status](https://www.travis-ci.com/vantage-sh/vantage-js.svg?branch=main)](https://www.travis-ci.com/vantage-sh/vantage-js)
+# @vantage-sh/vantage-client
 
-# Vantage Javascript Client
+A fully-typed TypeScript SDK for the [Vantage](https://vantage.sh) API. Types and client methods are auto-generated from the official OpenAPI specification.
 
-![Vantage Picture](https://uploads-ssl.webflow.com/5f9ba05ba40d6414f341df34/5f9bb1764b6670c6f7739564_moutain-scene.svg)
+## Installation
 
-[Vantage](http://vantage.sh/) is a cloud cost transparency platform. This is the official Ruby client for the [Vantage API](http://vantage.readme.io/). You can use the API to get EC2 instance price and product information through a few simple-to-use API calls. The data offered through this API is heavily inspired from data avaiable from [ec2instances.info](http://ec2instances.info/). The feedback we get from users is that this API is significantly easier than learning and using AWS Pricing APIs. We have plans to expand the data available through this API in the future.
+```bash
+npm install @vantage-sh/vantage-client
+```
 
-## Need Help?
+## Two Ways to Use
 
-Feel free to join us in our [community Slack](https://join.slack.com/t/vantagecommunity/shared_invite/zt-oey52myv-gq4AWRKkX25kjp1UGziPTw) in the #api channel. We're happy to chat and help. You're also welcome to email support@vantage.sh or ping [@JoinVantage](https://twitter.com/joinvantage) on Twitter and we're happy to give assistance. Lastly, we monitor issues on this repo if you have any feature requests or issues. 
+This SDK provides two distinct modes of operation: a **high-level resource API** for convenience, and a **low-level typed request method** for full control with complete type safety.
 
-## Installation
+### High-Level API
 
-The easiest way to get going is to install the client through RubyGems:
+The `APIV2Client` organizes endpoints by resource with intuitive CRUD methods:
 
-```shell
-npm i @vantage-sh/vantage-client --save
-```
+```typescript
+import { APIV2Client } from "@vantage-sh/vantage-client";
 
-## Generate a Free API Token
-The Vantage API is provided completely for free but requires an API token to use. To generate a free API token, follow these steps:
+const client = new APIV2Client("your-api-token");
 
-* Head to [http://vantage.sh/](http://vantage.sh/)
-* Register a free account and confirm your email
-* When you're asked _"What would you like to do first?"_ click _"Access Cloud Pricing API"_
-* Create an API token from the account profile page and you're all set
+// List resources with query parameters
+const reports = await client.costReports.list({ page: 1 });
 
-You'll only need to do this once and you can use your API token for all usage going forward. 
+// Get a specific resource by token
+const report = await client.costReports.get("rprt_abc123");
 
-## Client
+// Create a new resource
+const folder = await client.folders.create({
+  title: "Production Costs",
+  workspace_token: "wrkspc_123",
+});
+
+// Update a resource
+await client.folders.update("fldr_abc123", {
+  title: "Updated Title",
+});
 
-Vantage - JavaScript client for vantage
-Vantage API
-This SDK is automatically generated by the [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) project:
+// Delete a resource
+await client.folders.delete("fldr_abc123");
+```
 
-- API version: 1.0.0
-- Package version: 0.1.0-beta7
-- Build package: io.swagger.codegen.languages.JavascriptClientCodegen
-For more information, please visit [https://www.vantage.sh](https://www.vantage.sh)
+Resources with nested or specialized endpoints expose additional methods:
 
-## Getting Started
+```typescript
+// Access sub-resources
+const costs = await client.costs.getForCostReport("rprt_abc123", {
+  start_date: "2024-01-01",
+  end_date: "2024-01-31",
+});
+```
 
-Please follow the [installation](#installation) instruction and execute the following JS code:
+### Low-Level Typed Requests
 
-```javascript
-var Vantage = require('vantage');
+For full control, use the `request` method directly with path strings. The SDK provides **complete type safety** — TypeScript validates that your path exists, your method is supported, and your request/response bodies match the schema:
 
-var defaultClient = Vantage.ApiClient.instance;
+```typescript
+import { APIV2Client } from "@vantage-sh/vantage-client";
 
-// Configure OAuth2 access token for authorization: oauth2
-var oauth2 = defaultClient.authentications['oauth2'];
-oauth2.accessToken = "YOUR ACCESS TOKEN"
+const client = new APIV2Client("your-api-token");
 
-var api = new Vantage.CostsApi()
+// Path and method are type-checked against the OpenAPI schema
+const report = await client.request(
+  "/cost_reports/rprt_abc123",
+  "GET",
+  undefined
+);
 
-var reportId = "reportId_example"; // {String} 
+// TypeScript enforces correct body shape for POST/PUT/PATCH
+const newFolder = await client.request("/folders", "POST", {
+  title: "My Folder",
+  workspace_token: "wrkspc_123",
+});
 
-var opts = { 
-  'startDate': "startDate_example", // {String} Query costs by the first date you would like to filter from. ISO 8601 Formatted - 2021-07-15 or 2021-07-15T19:20:48+00:00.
-  'endDate': "endDate_example", // {String} Query costs by the last date you would like to filter to. ISO 8601 Formatted - 2021-07-15 or 2021-07-15T19:20:48+00:00.
-  'page': 2, // {Number} The page of results to return.
-  'limit': 500 // {Number} The amount of results to return. The maximum is 1000
-};
-api.getCosts(reportId, opts).then(function(data) {
-  console.log('API called successfully. Returned data: ' + data);
-}, function(error) {
-  console.error(error);
+// Query parameters are passed as the body for GET requests
+const reports = await client.request("/cost_reports", "GET", {
+  page: 1,
 });
+```
+
+#### Path Type Safety
 
+The `Path` type is a union of all valid API paths. TypeScript will error on invalid paths:
 
+```typescript
+// ✓ Valid path
+await client.request("/cost_reports", "GET", { page: 1 });
+
+// ✗ TypeScript error: invalid path
+await client.request("/not_a_real_endpoint", "GET", {});
+```
+
+#### Method Type Safety
+
+The `SupportedMethods<P>` type ensures only valid HTTP methods for each path:
+
+```typescript
+// ✓ GET is supported on /cost_reports
+await client.request("/cost_reports", "GET", { page: 1 });
+
+// ✗ TypeScript error: DELETE not supported on /cost_reports
+await client.request("/cost_reports", "DELETE", {});
+```
+
+#### Request/Response Types
+
+Import types for individual endpoints when needed:
+
+```typescript
+import type {
+  GetCostReportResponse,
+  CreateFolderRequest,
+  CreateFolderResponse,
+} from "@vantage-sh/vantage-client";
+
+function displayReport(report: GetCostReportResponse) {
+  console.log(report.title);
+}
 ```
 
-## Documentation for API Endpoints
+## Error Handling
 
-All URIs are relative to *https://api.vantage.sh*
+By default, API errors are thrown as `VantageAPIError` with structured error information:
+
+```typescript
+import { VantageAPIError } from "@vantage-sh/vantage-client";
+
+try {
+  await client.costReports.get("invalid_token");
+} catch (error) {
+  if (error instanceof VantageAPIError) {
+    console.log(error.status);     // 404
+    console.log(error.statusText); // "Not Found"
+    console.log(error.errors);     // ["Resource not found"] or null
+  }
+}
+```
 
-Class | Method | HTTP request | Description
------------- | ------------- | ------------- | -------------
-*Vantage.CostsApi* | [**getCosts**](docs/CostsApi.md#getCosts) | **GET** /v1/reports/{report_id}/costs | 
-*Vantage.CostsApi* | [**getReport**](docs/CostsApi.md#getReport) | **GET** /v1/reports/{report_id} | 
-*Vantage.CostsApi* | [**getReports**](docs/CostsApi.md#getReports) | **GET** /v1/reports | 
-*Vantage.PingApi* | [**ping**](docs/PingApi.md#ping) | **GET** /v1/ping | 
-*Vantage.PricesApi* | [**getPrice**](docs/PricesApi.md#getPrice) | **GET** /v1/products/{product_id}/prices/{id} | 
-*Vantage.PricesApi* | [**getPrices**](docs/PricesApi.md#getPrices) | **GET** /v1/products/{product_id}/prices | 
-*Vantage.PricesApi* | [**getProduct**](docs/PricesApi.md#getProduct) | **GET** /v1/products/{id} | 
-*Vantage.PricesApi* | [**getProducts**](docs/PricesApi.md#getProducts) | **GET** /v1/products | 
-*Vantage.PricesApi* | [**getProviders**](docs/PricesApi.md#getProviders) | **GET** /v1/providers | 
-*Vantage.PricesApi* | [**getServices**](docs/PricesApi.md#getServices) | **GET** /v1/services | 
+### Never Throw Mode
 
+For Go-style error handling without try/catch, enable never throw mode by passing `true` as the second argument to the client constructor:
 
-## Documentation for Models
+```typescript
+import { APIV2Client, VantageAPIError } from "@vantage-sh/vantage-client";
 
- - [Vantage.Cost](docs/Cost.md)
- - [Vantage.Costs](docs/Costs.md)
- - [Vantage.Price](docs/Price.md)
- - [Vantage.Prices](docs/Prices.md)
- - [Vantage.Product](docs/Product.md)
- - [Vantage.Products](docs/Products.md)
- - [Vantage.Provider](docs/Provider.md)
- - [Vantage.Providers](docs/Providers.md)
- - [Vantage.Report](docs/Report.md)
- - [Vantage.Reports](docs/Reports.md)
- - [Vantage.Service](docs/Service.md)
- - [Vantage.Services](docs/Services.md)
+const client = new APIV2Client("your-api-token", true);
 
+// All methods return [result, null] on success or [null, error] on failure
+const [report, error] = await client.costReports.get("rprt_abc123");
 
-## Documentation for Authorization
+if (error) {
+  console.log(error.status);  // 404
+  console.log(error.errors);  // ["Resource not found"]
+  return;
+}
+
+// TypeScript knows report is defined here
+console.log(report.title);
+```
+
+This pattern works with all client methods, including the low-level `request` method:
+
+```typescript
+const client = new APIV2Client("your-api-token", true);
+
+const [folders, error] = await client.request("/folders", "GET", { page: 1 });
+
+if (error) {
+  // Handle error
+  return;
+}
+
+// Use folders safely
+```
+
+## Utilities
+
+### Path Encoding
+
+Use `pathEncode` to safely encode dynamic path segments:
+
+```typescript
+import { pathEncode } from "@vantage-sh/vantage-client";
+
+const token = pathEncode(userProvidedToken);
+const report = await client.request(
+  `/cost_reports/${token}`,
+  "GET",
+  undefined
+);
+```
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+This fetches the latest OpenAPI schema from the Vantage API, generates TypeScript types, and compiles the client.
+
+### Type Checking
+
+```bash
+npm run type-check
+```
+
+### Multipart Edge Cases
+
+The client automatically detects `multipart/form-data` routes and handles them appropriately. However, this detection requires a manually-maintained mapping in `BaseClient.ts`:
+
+```typescript
+const multipartEdgeCases: MultipartEdgeCases = {
+  "/exchange_rates/csv": {
+    POST: true,
+  },
+  "/business_metrics/{}/values.csv": {
+    PUT: true,
+  },
+  // ...
+};
+```
 
+The `MultipartEdgeCases` type is derived from the OpenAPI schema. If a new multipart route is added to the API, **TypeScript will produce an error** until you add the route to this object. Path parameters are represented as `{}` in the keys.
 
-### oauth2
+### Type Helpers
 
-- **Type**: OAuth
-- **Flow**: application
-- **Authorization URL**: 
-- **Scopes**: 
-  - read: Grants read access
+The SDK exports several utility types for advanced use:
 
+| Type | Description |
+|------|-------------|
+| `Path` | Union of all valid API paths |
+| `SupportedMethods<P>` | Valid HTTP methods for a given path |
+| `RequestBodyForPathAndMethod<P, M>` | Request body type for a path/method |
+| `ResponseBodyForPathAndMethod<P, M>` | Response body type for a path/method |
+| `NoSlashString` | Branded type for safely encoded path segments |