|
1 | | -# typescript-sdk |
| 1 | +# @team-plain/typescript-sdk |
2 | 2 |
|
3 | | -This is the Typescript/JS SDK for Plain.com's Core API. It allows you to do basic actions. |
| 3 | +[Changelog]('./CHANGELOG.md') |
| 4 | + |
| 5 | +This is the typescript/node SDK for Plain.com's Core GraphQL API. It makes it easy to make common API calls in just a few lines of code. |
| 6 | + |
| 7 | +If you run into any issues please open an issue or get in touch with us at help@plain.com. |
| 8 | + |
| 9 | +## Basic example |
| 10 | + |
| 11 | +```ts |
| 12 | +import { PlainSDKClient } from "@team-plain/typescript-sdk" |
| 13 | + |
| 14 | +const client = new PlainSDKClient({ |
| 15 | + apiKey: 'plainApiKey__tmRD_xF5qiMH0657LkbLCC1maN4hLsBIbyOgjqEP4w' |
| 16 | +}) |
| 17 | + |
| 18 | +const result = await client.getCustomerById({ customerId: 'c_01GHC4A88A9D49Q30AAWR3BN7P' }); |
| 19 | + |
| 20 | +if (result.error) { |
| 21 | + console.log(result.error); |
| 22 | +} else { |
| 23 | + console.log(result.data.fullName); |
| 24 | +} |
| 25 | +``` |
| 26 | + |
| 27 | +You can find out how to make an API key in our documentation: https://docs.plain.com/core-api/authentication |
| 28 | + |
| 29 | + |
| 30 | +## Documentation |
| 31 | + |
| 32 | +Every method in the SDK corresponds to a graphql [query](./src/graphql/queries/) or [mutation](./src/graphql/mutations/). |
| 33 | + |
| 34 | +You can find the generated documentation here: |
| 35 | + |
| 36 | +**[Documentation](https://plain-typescript-sdk-docs.vercel.app/classes/PlainSDKClient.html)** |
| 37 | + |
| 38 | +If you would like to add a query or mutation please open an issue and we can add it for you. |
| 39 | + |
| 40 | + |
| 41 | +## Error handling |
| 42 | +Every SDK method will return an object with either data or an error. |
| 43 | + |
| 44 | +**You will either receive an error or data, never both.** |
| 45 | + |
| 46 | +Here is an example: |
| 47 | + |
| 48 | +```ts |
| 49 | +const client = new PlainSDKClient({ |
| 50 | + apiKey: 'plainApiKey__tmRD_xF5qiMH0667LkbLCC1maN2hLsBIbyOgjqEP4w' |
| 51 | +}) |
| 52 | + |
| 53 | +function doThing() { |
| 54 | + const result = await client.getCustomerById({ customerId: 'c_01GHC4A88A9D49Q30AAWR3BN7P' }); |
| 55 | + |
| 56 | + if (result.error) { |
| 57 | + console.log(result.error); |
| 58 | + } else { |
| 59 | + console.log(result.data.fullName); |
| 60 | + } |
| 61 | +} |
| 62 | +``` |
| 63 | + |
| 64 | +An error can be **one of** the below: |
| 65 | + |
| 66 | +### MutationError |
| 67 | +[(view source)](./src/error.ts) |
| 68 | +This is the richest error type. It is called `MutationError` since it maps to the `MutationError` type in our GraphQL schema and is returned as part of every mutation in our API. |
| 69 | + |
| 70 | +You can view the full details of this error under `errorDetails`. |
| 71 | + |
| 72 | +Every mutation error will contain: |
| 73 | +- **message**: an English technical description of the error. This error is usually meant to be read by a developer and not an end user. |
| 74 | +- **type**: one of `VALIDATION`, `FORBIDDEN`, `INTERNAL`. See [MutationErrorType](https://docs.plain.com/core-api/reference/enums/mutation-error-type) for a description of each value. |
| 75 | +- **code**: a unique error code for each type of error returned. This code can be used to provide a localized or user-friendly error message. You can find the list of error codes [in our docs](https://docs.plain.com/error-codes) . |
| 76 | +- **fields**: an array containing all the fields that errored. Each field: |
| 77 | + - **field**: the name of the input field the error is for |
| 78 | + - **message**: an English technical description of the error. This error is usually meant to be read by a developer and not an end user. |
| 79 | +type: one of `VALIDATION`, `REQUIRED`, `NOT_FOUND`. See [MutationFieldErrorType](https://docs.plain.com/core-api/reference/enums/mutation-field-error-type) for a description of each value. |
| 80 | + |
| 81 | +### BadRequestError |
| 82 | +[(view source)](./src/error.ts) |
| 83 | +Equivalent to a 400 response. If you are using typescript it's unlikely you will run into this since types will prevent this but if you are using javascript this likely means you are providing a wrong input/argument to a query or mutation. |
| 84 | + |
| 85 | +### ForbiddenError |
| 86 | +[(view source)](./src/error.ts) |
| 87 | +Equivalent to a 401 or 403 response. Normally means your API key doesn't exist or that you are trying to query something that you do not have permissions for. |
| 88 | + |
| 89 | +### InternalServerError |
| 90 | +[(view source)](./src/error.ts) |
| 91 | +Equivalent to a 500 response. If this happens something unexpected within Plain happened. |
4 | 92 |
|
5 | | -This is a work in progress. Docs are coming soon! |
|
0 commit comments