Merge pull request #130 from poap-xyz/remove-examples-add-documentation

Move examples to documentation

docs/pages/index.mdx

@@ -1,4 +1,4 @@
-> [!WARNING]
+> WARNING
 >
 > The POAP SDK is still in active initial development phase. Anything MAY change at any time.
 >

docs/pages/packages/drops/CreateDrop.mdx

@@ -0,0 +1,47 @@
+# Create Drop
+
+Using `DropsClient` to [setup a Drop](https://poap.zendesk.com/hc/en-us/articles/9702718846989-How-do-I-set-up-a-POAP-Drop)
+is straightforward, there is no need of being authenticated with an email and
+the only requiriments are having the API key.
+
+```typescript
+import fsPromises from 'fs/promises';
+import { Drop } from '@poap-xyz/drops';
+
+// The artwork of the Drop as loaded from the filesystem.
+const buffer = await fsPromises.readFile('path/to/poap-artwork.png');
+const image = new Blob([buffer], { type: 'image/png' });
+
+const drop: Drop = await client.create({
+  name: 'My super event to celebrate!',
+  description: 'Share the moment with all my invitees to celebrate.\nWe spend great time together.',
+  eventUrl: 'https://poap.xyz',
+
+  // Where that it takes place.
+  city: 'Buenos Aires',
+  country: 'Argentina',
+  virtualEvent: false,
+
+  // Not to be shared.
+  privateEvent: true,
+
+  // When does it start and when does it end.
+  startDate: new Date(2024, 6, 24),
+  endDate: new Date(2024, 6, 25),
+  expiryDate: new Date(2024, 7, 24),
+
+  // A password to edit my Drop.
+  secretCode: '123456',
+
+  // The artwork.
+  image,
+  filename: 'my-super-event-artwork.png',
+  contentType: 'image/png',
+
+  // A valid email where I will receive the mint links.
+  email: '[email protected]',
+
+  // The number of invitees in my event.
+  requestedCodes: 10,
+});
+```

docs/pages/packages/drops/FetchDrops.mdx

@@ -0,0 +1,39 @@
+# Fetch Drops
+
+When retrieving Drops we have to paginated using `offset` and `limit`. But besides we can sort the
+results and filter them by many options.
+
+```typescript
+import { Drop, DropsSortFields } from '@poap-xyz/drops';
+import { Order, PaginatedResult } from '@poap-xyz/utils';
+
+const paginatedDrops: PaginatedResult<Drop> = await client.fetch({
+  offset: 0,
+  limit: 10,
+  sortField: DropsSortFields.Id,
+  sortDir: Order.ASC,
+});
+```
+
+## Fetch single Drop
+
+By giving the Drop ID we want to find, we can filter the pagination to contain the Drop or not.
+
+```typescript
+import { Drop } from '@poap-xyz/drops';
+import { PaginatedResult } from '@poap-xyz/utils';
+
+const dropId = 14;
+
+const paginatedDrops: PaginatedResult<Drop> = await client.fetch({
+  offset: 0,
+  limit: 10,
+  ids: [dropId],
+});
+
+if (paginatedDrops.items.length === 0) {
+  throw new Error('My super drop was not found');
+}
+
+const drop: Drop = paginatedDrops.items[0];
+```

docs/pages/packages/drops/SearchDrops.mdx

@@ -8,13 +8,16 @@ search in name and description.
 When searching for a whole word, use `fetch` method:
 
 ```typescript
-  const data: PaginatedResult<Drop> = await dropsClient.fetch({
-    sortField: DropsSortFields.Name,
-    sortDir: Order.ASC,
-    limit: 3,
-    offset: 0,
-    name: 'POAP',
-  });
+import { Drop } from '@poap-xyz/drops';
+import { PaginatedResult } from '@poap-xyz/utils';
+
+const paginatedDrops: PaginatedResult<Drop> = await dropsClient.fetch({
+  sortField: DropsSortFields.Name,
+  sortDir: Order.ASC,
+  limit: 3,
+  offset: 0,
+  name: 'POAP',
+});
 ```
 
 ## Fuzzy search
@@ -23,9 +26,12 @@ When given a generic search input, and to match any part of the words used in
 the name of the description, use `search` method:
 
 ```typescript
-  const data: PaginatedResult<Drop> = await dropsClient.search({
-    limit: 3,
-    offset: 0,
-    search: 'POAP',
-  });
+import { Drop } from '@poap-xyz/drops';
+import { PaginatedResult } from '@poap-xyz/utils';
+
+const paginatedDrops: PaginatedResult<Drop> = await dropsClient.search({
+  limit: 3,
+  offset: 0,
+  search: 'POAP',
+});
 ```

docs/pages/packages/drops/_meta.json

@@ -1,3 +1,5 @@
 {
+  "CreateDrop": "Create Drop",
+  "FetchDrops": "Fetch Drops",
   "SearchDrops": "Search Drops"
 }

examples/frames/src/frames/buttons.ts → docs/pages/packages/frames/Examples.mdx

@@ -1,6 +1,24 @@
+# Examples
+
+## Basic
+
+```typescript
+import { Frame, FrameAspectRatio } from '@poap-xyz/frames';
+
+const frame = new Frame({
+  title: 'Hello World',
+  image: 'https://placehold.co/600x600',
+  aspectRatio: FrameAspectRatio.SQUARE,
+  postUrl: 'https://poap.xyz',
+});
+```
+
+## With Buttons
+
+```typescript
 import { Frame, FrameAspectRatio, FrameButtonAction } from '@poap-xyz/frames';
 
-export const FRAME_WITH_BUTTONS = new Frame({
+const frameWithButtons = new Frame({
   title: 'Hello World',
   image: 'https://placehold.co/600x600',
   aspectRatio: FrameAspectRatio.SQUARE,
@@ -19,3 +37,4 @@ export const FRAME_WITH_BUTTONS = new Frame({
     },
   ],
 });
+```

docs/pages/packages/frames/Render.mdx

@@ -0,0 +1,19 @@
+# Render Frame
+
+The `Frame` class has two methods to be rendered.
+
+## Meta tags
+
+To get a list of generated meta tags, use `toMetaTags` method.
+
+```typescript
+const metaTags = frame.toMetaTags();
+```
+
+## Render
+
+To render HTML directly use `render` method.
+
+```typescript
+frame.render();
+```

docs/pages/packages/frames/_meta.json

@@ -0,0 +1,4 @@
+{
+  "Render": "Render",
+  "Examples": "Examples"
+}

docs/pages/packages/moments/FetchMoments.mdx

@@ -0,0 +1,57 @@
+# Fetch Moments
+
+## List Moments
+
+Fetching moments per page are done by giving an `offset` and a `limit`. This way
+all the uploaded moments could be retrieved.
+
+```typescript
+import { Moment } from '@poap-xyz/moments';
+import { Order, PaginatedResult } from '@poap-xyz/utils';
+
+const paginatedMoments: PaginatedResult<Moment> = await client.fetch({
+  offset: 0,
+  limit: 10,
+  idOrder: Order.DESC,
+});
+```
+
+### By Drop
+
+The list can be filtered by one or more Drops by giving `drop_ids` list with the
+Drop IDs. Also, the list can be sorted by `id`, `created`, `tokenId` or `dropId`.
+
+```typescript
+import { Moment } from '@poap-xyz/moments';
+import { Order, PaginatedResult } from '@poap-xyz/utils';
+
+const dropId = 14;
+
+const paginatedMoments: PaginatedResult<Moment> = await client.fetch({
+  offset: 0,
+  limit: 10,
+  drop_ids: [dropId],
+  idOrder: Order.DESC,
+});
+```
+
+## Fetch single Moment
+
+```typescript
+import { Moment } from '@poap-xyz/moments';
+import { PaginatedResult } from '@poap-xyz/utils';
+
+const momentId = '7284219b-1bc7-43b8-ab27-44749bdd91e1';
+
+const paginatedMoments: PaginatedResult<Moment> = await client.fetch({
+  offset: 0,
+  limit: 1,
+  id: momentId,
+});
+
+if (paginatedMoments.items.length === 0) {
+  throw new Error('My moment does not exists');
+}
+
+const moment: Moment = paginatedMoments.items[0];
+```

docs/pages/packages/moments/UpdateMoment.mdx

@@ -0,0 +1,12 @@
+# Update Moment
+
+## Update CID
+
+```typescript
+const momentId = 'b08fad41-7154-499f-88f9-abea66ceab48';
+const cid = '0001-7ce5368171cc3d988157d7dab3d313d7bd43de3e-365e5b83699adce0825021d011f1bf73bd5ef9369d06e49645afbea2ef34f54e0557c1d4742c8bd6d1f7a02be4aa483c03888af0aa143d5aa7351e2baaf931231c.moment';
+
+await client.patchMoment(momentId, {
+  cid,
+});
+```

docs/pages/packages/moments/UploadMoments.mdx

@@ -6,17 +6,44 @@ upload an image and create it as a moment associated with a Drop or a POAP.
 ## From Node.js
 
 ```typescript
+import mime from 'mime';
 import fsPromises from 'fs/promises';
 import { Moment } from '@poap-xyz/moments';
 
+// Load the image of the moment.
+const fileBuffer = await fsPromises.readFile('path/to/poap-moment.png');
+const mimeType = mime.getType('path/to/poap-moment.png');
+
+// Upload it.
 const moment: Moment = await client.createMoment({
+  /**
+   * Moments are associated with a Drop.
+   */
   dropId: 110148,
+
   /**
-    * The Token ID related to the moment (Optional)
+    * The Token ID related to the moment (optional).
     */
   tokenId: 6568008,
-  mimeType: 'image/png',
-  file: await fsPromises.readFile('path/to/file.png'),
+
+  /**
+   * Who is uploading the moment.
+   */
   author: '0x82AB2941Cf555CED5ad7Ed232a5B5f6083815FBC',
+
+  /**
+   * The list of images in the moment.
+   */
+  media: [
+    {
+      fileBinary: fileBuffer,
+      fileType: mimeType,
+    },
+  ],
+
+  /**
+   * Some text to describe the moment.
+   */
+  description: 'Look how much fun we were having!',
 });
 ```

docs/pages/packages/moments/_meta.json

@@ -1,3 +1,5 @@
 {
-  "UploadMoments": "Upload Moments"
+  "FetchMoments": "Fetch Moments",
+  "UploadMoments": "Upload Moments",
+  "UpdateMoment": "Update Moment"
 }

docs/pages/packages/poaps/EmailReservation.mdx

@@ -0,0 +1,18 @@
+# Email Reservation
+
+A POAP can be reserved with an email where to receive the instructions to mint
+the it to the blockchain in the future. The email could be not be send in cases
+that another email is send in their place or the collector knows already how to
+mint it afterwards.
+
+```typescript
+import { POAPReservation } from '@poap-xyz/poaps';
+
+const emailReservation: POAPReservation = await client.emailReservation({
+  mintCode: 'your_poap_code',
+  email: '[email protected]',
+  sendEmail: true,
+});
+```
+
+This method can throw [custom errors](Errors) that need to handled.

docs/pages/packages/poaps/Errors.mdx

@@ -9,10 +9,15 @@ These custom error classes allow for more precise error handling and better debu
 Below example demonstrates how one might use the `PoapsClient` class along with the custom error handling.
 
 ```typescript
-import { FinishedWithError } from '@poap-xyz/poaps';
+import {
+  POAP,
+  FinishedWithError,
+  CodeAlreadyMintedError,
+  CodeExpiredError,
+} from '@poap-xyz/poaps';
 
 try {
-  const poap = await client.mintSync({
+  const poap: POAP = await client.mintSync({
     mintCode: 'some-mint-code',
     address: '0x1234567890abcdef1234567890abcdef12345678',
   });