feat: support idempotency (#58)

docs/api/idempotency.mdx

@@ -0,0 +1,93 @@
+---
+title: Idempotency
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import {Alert} from "@site/src/components/shared/Alert";
+
+# Idempotency
+
+Basis Theory supports idempotency to guarantee multiple retries of the same request do not
+unintentionally perform the same operation more than once.
+
+Our API endpoints accept a client-provided `Idempotency Key` if sent with the `BT-IDEMPOTENCY-KEY` `HTTP` header within `POST`, `PUT` and `PATCH` methods.
+
+If an `Idempotency Key` is not provided by the client, retrying the same request might result in unwanted behavior.
+
+The `Idempotency Key` must be a unique value generated by the client which is used by the Basis Theory
+API to identify subsequent requests belong to an original request. The `Idempotency Key` generation is up to the
+client, but we strongly recommend using a unique identifier such as `UUID` to avoid collisions.
+
+When the first request comes in, its response status code and body is saved. Whenever a subsequent
+request comes in with the same `Idempotency Key`, the previous stored result will be returned if it
+succeeded. If the first request failed, the result is not stored and a subsequent request with the
+same `Idempotency Key` is processed as a new request. If any subsequent request comes in while
+the first is still processing, a `409` status code is returned.
+
+If an `Idempotency Key` is provided for a `GET` or `DELETE` request, it is ignored and idempotency logic
+is not invoked, since these `HTTP` verbs are idempotent by definition.
+
+All idempotency keys and their respective results are deleted after 24 hours. Therefore, if an
+`Idempotency Key` is reused after 24 hours, it will be handled as a new request.
+
+<Alert>
+  <code>Proxy</code> requests do not currently support idempotency. <a href="https://basistheory.com/contact">Please
+  reach out</a> if you would like this capability.
+</Alert>
+
+### Example
+
+<Tabs className="bt-tabs" groupId="languages">
+  <TabItem value="shell" label="cURL">
+
+```shell showLineNumbers
+curl "https://api.basistheory.com" \
+-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
+-H "BT-IDEMPOTENCY-KEY: aa5d3379-6385-4ef4-9fdb-ca1341572153"
+```
+
+  </TabItem>
+  <TabItem value="javascript" label="JavaScript">
+
+```javascript showLineNumbers
+import {BasisTheory} from "@basis-theory/basis-theory-js";
+
+const bt = await new BasisTheory().init("key_N88mVGsp3sCXkykyN2EFED");
+
+const applications = await bt.tokens.create(
+{},
+{
+  idempotencyKey: "aa5d3379-6385-4ef4-9fdb-ca1341572153",
+}
+);
+```
+
+  </TabItem>
+  <TabItem value="csharp" label="C#">
+
+```csharp showLineNumbers
+using BasisTheory.net.Tokens;
+
+var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");
+
+client.GetAsync(requestOptions: new RequestOptions {
+IdempotencyKey = "aa5d3379-6385-4ef4-9fdb-ca1341572153"
+});
+```
+
+  </TabItem>
+  <TabItem value="python" label="Python">
+
+```python showLineNumbers
+import basistheory
+from basistheory.api import tokens_api
+
+api_client = basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED"))
+client = tokens_api.TokensApi(api_client)
+
+client.create(request_options=basistheory.RequestOptions(idempotency_key="aa5d3379-6385-4ef4-9fdb-ca1341572153"))
+```
+
+  </TabItem>
+</Tabs>

sidebars.js

@@ -211,6 +211,7 @@ const sidebars = {
         "api/errors",
         "api/ip-addresses",
         "api/rate-limits",
+        "api/idempotency"
       ],
     },
     {