feat: sdk docs

Author: designcode

docs/sdks/tigris/index.mdx

@@ -3,19 +3,41 @@
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-The Tigris Storage SDK is a simplified wrapper around the Tigris Data API. It
-provides a simpler interface and minimal configuration that lets you get started
-quickly and integrate Tigris into your application. It offers all the
-functionality of the Tigris Data, but with a simpler interface.
+The Tigris Storage SDK is a simplified wrapper around the Tigris Object Storage
+API. It provides a simpler interface and minimal configuration that lets you get
+started quickly and integrate Tigris into your application. It offers all the
+functionality of the Tigris, but with a simpler interface.
 
-Tigris Storage SDK is geared towards application developers who needs to store
-objects that:
+## Use Cases
+
+Tigris Storage SDK is geared (but not limited to) towards application developers
+who needs to store objects that:
 
 - Are programmatically uploaded or generated at build time, for display and
   download such as avatars, screenshots, cover images and videos
 - Are larger and not practical to store in the database, such as images, videos,
-  etc.
+  documents, etc.
 - That needs to be retrieved frequently across different regions
+- break your wallet by paying egress fees
+
+## Key Features
+
+As mentioned above, Tigris Storage SDK offers all the great features of the
+Tigris Object Storage API. Some of the key features are:
+
+- **[Global](/docs/objects/object_regions/):** Access your data from any region
+  by using a single global endpoint. Tigris is inherently global. However, if
+  you need to store data in single or multiple regions, you can do so by simply
+  configuring the bucket regions. Check out the
+  [Multi-Region Buckets](/docs/buckets/multi-region/) section.
+- **[Zero egress fees](/docs/pricing/):** Access your data freely. Stop paying
+  just to use your own data. From storing large datasets for your AI workflows
+  to storing small files, those egress fees can add up quickly. Tigris offers
+  world class object storage for the fraction of the cost of other providers.
+- **[Blazing fast](/blog/benchmark-small-objects/):** Tigris is 5.3x faster than
+  S3 and 86.6x faster than R2 for small object reads. If your workload depends
+  on reading lots of small objects—logs, AI features, or massive number of tiny
+  files—this matters.
 
 ## Getting Started
 
@@ -71,7 +93,7 @@ supports both CommonJS and ES6 Modules syntax. That means you can use both
 ```js
 import { list } from "@tigrisdata/storage";
 
-const objects = await list(); // lists objects in bucket $BUCKET_NAME
+const objects = await list(); // lists objects in bucket TIGRIS_STORAGE_BUCKET
 console.log(objects);
 ```
 
@@ -99,143 +121,211 @@ more than happy to add in examples.
 
 ### Viewing and downloading files
 
-`get` function can be used to get a file from a bucket.
+`get` function can be used to get a file from a bucket. `contentDisposition`
+option can be to either `attachment` or `inline` depending on whether you want
+to trigger a download or display the file in the browser.
 
 <Tabs>
-<TabItem value="es6mod" label="ES6 Modules" default>
+<TabItem value="server" label="Server" default>
 
-```js
+```ts
+// app/api/avatar.ts
+import { NextRequest, NextResponse } from "next/server";
 import { get } from "@tigrisdata/storage";
 
-const result = await get("my-file.jpg");
-```
-
-</TabItem>
-<TabItem value="commonjs" label="CommonJS Modules">
+export async function GET(
+  req: NextRequest,
+): Promise<NextResponse<File | string>> {
+  const avatar = req.nextUrl.searchParams.get("avatar");
 
-```js
-const { get } = require("@tigrisdata/storage");
+  if (!avatar) {
+    return NextResponse.json("avatar parameter is required", { status: 400 });
+  }
 
-get("my-file.jpg").then((result) => {
-  console.log(result);
-});
-```
+  try {
+    const avatarPath = decodeURIComponent(avatar as string);
 
-</TabItem>
-</Tabs>
+    const file = await get(avatarPath, "file", {
+      contentDisposition: "inline",
+    });
 
-To trigger a download, you can use the `contentDisposition` option.
+    if (file.data) {
+      return new NextResponse(file.data, { status: 200 });
+    }
 
-<Tabs>
-<TabItem value="es6mod" label="ES6 Modules" default>
+    if (file.error && file.error.message) {
+      return NextResponse.json(file.error.message, { status: 500 });
+    }
+  } catch (error) {
+    return NextResponse.json(
+      error instanceof Error ? error.message : "Unknown error",
+      { status: 500 },
+    );
+  }
 
-```js
-const result = await get("my-file.pdf", { contentDisposition: "attachment" });
+  return NextResponse.json("No data found", { status: 404 });
+}
 ```
 
 </TabItem>
-<TabItem value="commonjs" label="CommonJS Modules">
-
-```js
-const { get } = require("@tigrisdata/storage");
-
-get("my-file.pdf", { contentDisposition: "attachment" }).then((result) => {
-  console.log(result);
-});
+<TabItem value="client" label="Client">
+
+```tsx
+import Image from "next/image";
+
+export default function Avatar() {
+  const { user } = getUserData();
+
+  return (
+    <Image
+      src={`/api/avatar?avatar=${encodeURIComponent(user.avatar)}`}
+      alt="Avatar"
+      width={100}
+      height={100}
+    />
+  );
+}
 ```
 
 </TabItem>
 </Tabs>
 
-You can also use the `contentType` option to set the content type of the file.
+To trigger a download, set the `contentDisposition` option to `attachment`.
 
-### Getting list of objects
+### Uploading files
 
-`list` function can be used to get a list of objects in a bucket.
+`put` function can be used to upload a file to a bucket.
 
 <Tabs>
-<TabItem value="es6mod" label="ES6 Modules" default>
+<TabItem value="server" label="Server" default>
 
-```javascript
-import { list } from "@tigrisdata/storage";
+```ts
+// app/api/upload.ts
+import { NextRequest, NextResponse } from "next/server";
+import { put } from "@tigrisdata/storage";
+
+export async function PUT(req: NextRequest) {
+  const formData = await req.formData();
+  const file = formData.get("file") as File;
+
+  if (!file) {
+    return NextResponse.json({ error: "No file provided" }, { status: 400 });
+  }
+
+  const result = await put(file.name, file, {
+    access: "public",
+    addRandomSuffix: false,
+  });
+
+  if (result.error) {
+    return NextResponse.json({ error: result.error.message }, { status: 500 });
+  }
 
-// List first 100 objects
-const result = await list({ limit: 100 });
+  return NextResponse.json({ data: result.data }, { status: 200 });
+}
 ```
 
 </TabItem>
-<TabItem value="commonjs" label="CommonJS Modules">
-
-```javascript
-const { list } = require("@tigrisdata/storage");
+<TabItem value="client" label="Client">
+
+```tsx
+export default function Upload() {
+  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+
+    if (file) {
+      const formData = new FormData();
+      formData.append("file", file);
+      fetch("/api/test", {
+        method: "PUT",
+        body: formData,
+      });
+    }
+  };
 
-// List first 100 objects
-list({ limit: 100 }).then((result) => {
-  console.log(result);
-});
+  return <input type="file" onChange={handleFileChange} />;
+}
 ```
 
 </TabItem>
 </Tabs>
 
-Tigris Storage SDK supports pagination of results.
+### Client side uploads
 
-<Tabs>
-<TabItem value="es6mod" label="ES6 Modules" default>
+Amongst all the other great features of Tigris Storage SDK, free egress fees is
+a what makes us stand out from other providers. We care about the bandwidth
+costs and we want to make it as cheap as possible for you to use Tigris. That's
+why we've made it so that you can upload files directly to Tigris from the
+client side.
+
+We leverage the presigned URLs features to allow you to upload files directly to
+Tigris from the client side.
 
-```javascript
-let allFiles = [];
-let currentPage = await list({ limit: 50 });
+<Tabs>  
+<TabItem value="server" label="Server" default>
 
-if (currentPage.data) {
-  allFiles.push(...currentPage.data.items);
+```ts
+// app/api/signed.ts
+import { NextRequest, NextResponse } from "next/server";
+import { getPresignedUrl } from "@tigrisdata/storage";
 
-  while (currentPage.data.hasMore && currentPage.data.paginationToken) {
-    currentPage = await list({
-      limit: 50,
-      paginationMarker: currentPage.data.paginationToken,
+export async function POST(request: NextRequest) {
+  try {
+    const { path, method, contentType } = await request.json();
+    const result = await getPresignedUrl(path, {
+      method,
+      contentType,
+      expiresIn: 3600, // 1 hour
     });
 
-    if (currentPage.data) {
-      allFiles.push(...currentPage.data.items);
-    } else if (currentPage.error) {
-      console.error("Error during pagination:", currentPage.error);
-      break;
-    }
+    return NextResponse.json({ data: result.data });
+  } catch (error) {
+    console.error("Upload error:", error);
+    return NextResponse.json(
+      { error: "Failed to generate presigned URL" },
+      { status: 500 },
+    );
   }
 }
 ```
 
 </TabItem>
-<TabItem value="commonjs" label="CommonJS Modules">
-
-```javascript
-const { list } = require("@tigrisdata/storage");
 
-(async () => {
-  let allFiles = [];
-  let currentPage = await list({ limit: 50 });
+<TabItem value="client" label="Client">
+```tsx
+"use client";
+
+import { upload } from "@tigrisdata/storage/client";
+import { useState } from "react";
+
+export default function ClientUpload() {
+  const [progress, setProgress] = useState<number>(0);
+  const [url, setUrl] = useState<string | null>(null);
+  const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    setProgress(0);
+    if (file) {
+      const result = await upload(`${file.name}`, file, {
+        url: "/api/test",
+        access: "private",
+        onUploadProgress: ({ loaded, total, percentage }) => {
+          setProgress(percentage);
+          if (percentage === 100) {
+            setProgress(0);
+          }
+        },
+      });
+      setUrl(result.url);
+    }
+  };
 
-  if (currentPage.data) {
-    allFiles.push(...currentPage.data.items);
+return ( <><input type="file" onChange={handleFileChange} /> {url &&
 
-    while (currentPage.data.hasMore && currentPage.data.paginationToken) {
-      currentPage = await list({
-        limit: 50,
-        paginationMarker: currentPage.data.paginationToken,
-      });
+<div>Uploaded to: {url}</div>} {progress > 0 && progress < 100 &&
+<div>{progress}%</div>} </> ); }
 
-      if (currentPage.data) {
-        allFiles.push(...currentPage.data.items);
-      } else if (currentPage.error) {
-        console.error("Error during pagination:", currentPage.error);
-        break;
-      }
-    }
-  }
-  console.log(allFiles);
-})();
 ```
 
 </TabItem>
 </Tabs>
+```

sidebars.js

@@ -229,13 +229,9 @@ const sidebars = {
       ],
     },
     {
-      type: "category",
-      label: "Tigris Storage SDK",
-      link: {
-        type: "doc",
-        id: "sdks/tigris/index",
-      },
-      items: ["sdks/tigris/api-reference"],
+      type: "doc",
+      label: "Tigris SDK",
+      id: "sdks/tigris/index",
     },
     {
       type: "category",