### Example Pagination Usage in TypeScript

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/pagination.md

Demonstrates how to import and instantiate the Pagination model in TypeScript. This example shows the structure of a Pagination object with all its fields.

```typescript
import { Pagination } from "@usemarble/sdk/models";

let value: Pagination = {
  limit: 10,
  currentPage: 1,
  nextPage: 2,
  previousPage: null,
  totalPages: 5,
  totalItems: 42,
};
```

--------------------------------

### Install @usemarble/sdk Package

Source: https://context7.com/usemarble/marble-ts/llms.txt

Installs the Marble SDK package using various package managers like npm, pnpm, yarn, or bun.

```bash
npm add @usemarble/sdk
# or
pnpm add @usemarble/sdk
# or
yarn add @usemarble/sdk
# or
bun add @usemarble/sdk
```

--------------------------------

### Install @usemarble/sdk using NPM, PNPM, Bun, or Yarn

Source: https://github.com/usemarble/marble-ts/blob/main/README.md

Instructions for installing the @usemarble/sdk package using popular JavaScript package managers like NPM, PNPM, Bun, and Yarn. The package supports both CommonJS and ES Modules (ESM).

```bash
npm add @usemarble/sdk
```

```bash
pnpm add @usemarble/sdk
```

```bash
bun add @usemarble/sdk
```

```bash
yarn add @usemarble/sdk
```

--------------------------------

### Example Usage of TagsListResponse in TypeScript

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/tagslistresponse.md

Demonstrates how to instantiate and use the TagsListResponse model in TypeScript. This example shows the expected structure for tags and pagination data.

```typescript
import { TagsListResponse } from "@usemarble/sdk/models";

let value: TagsListResponse = {
  tags: [
    {
      id: "cryitfjp4567no07ygqadhm1",
      name: "JavaScript",
      slug: "javascript",
      description: "JavaScript tutorials",
      count: {
        posts: 8,
      },
    },
  ],
  pagination: {
    limit: 10,
    currentPage: 1,
    nextPage: 2,
    previousPage: null,
    totalPages: 5,
    totalItems: 42,
  },
};

```

--------------------------------

### PostResponse Model Example (TypeScript)

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/postresponse.md

Demonstrates how to import and use the PostResponse model from the @usemarble/sdk in TypeScript. This example shows the structure of a typical PostResponse object, including nested post details, author information, category, and tags.

```typescript
import { PostResponse } from "@usemarble/sdk/models";

let value: PostResponse = {
  post: {
    id: "cryitfjp5678mn09qrstuvwx",
    slug: "getting-started-with-nextjs",
    title: "Getting Started with Next.js",
    content: "<p>Hello world</p>",
    featured: false,
    coverImage: "https://media.marblecms.com/cover.jpg",
    description: "A beginner's guide to Next.js",
    publishedAt: new Date("2024-01-15T10:00:00Z"),
    updatedAt: new Date("2024-01-16T12:00:00Z"),
    attribution: {
      author: "John Doe",
      url: "https://original-source.com/article",
    },
    authors: [
      {
        id: "cryitfjp1234jl04vdnycek8",
        name: "John Doe",
        image: "https://media.marblecms.com/avatar.jpg",
        bio: "Technical writer and developer",
        role: "Editor",
        slug: "john-doe",
        socials: [],
      },
    ],
    category: {
      id: "cryitfjp1234jl04vdnycek8",
      name: "Technology",
      slug: "technology",
      description: "Tech news and tutorials",
    },
    tags: [
      {
        id: "cryitfjp1234jl04vdnycek8",
        name: "JavaScript",
        slug: "javascript",
        description: "JavaScript tutorials",
      },
    ],
  },
};

```

--------------------------------

### Get Author Data using Marble SDK (TypeScript)

Source: https://github.com/usemarble/marble-ts/blob/main/docs/sdks/authors/README.md

Demonstrates how to fetch author information using the `get` method from the Marble SDK's authors module. It initializes the Marble client with an API key and calls the `get` method with an author identifier. Requires the @usemarble/sdk package.

```typescript
import { Marble } from "@usemarble/sdk";

const marble = new Marble({
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
});

async function run() {
  const result = await marble.authors.get({
    identifier: "john-doe",
  });

  console.log(result);
}

run();
```

--------------------------------

### AuthorsListResponse Model Example Usage (TypeScript)

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/authorslistresponse.md

Demonstrates how to instantiate and use the AuthorsListResponse model in TypeScript. This example shows the structure of the response, including the list of authors and pagination details.

```typescript
import { AuthorsListResponse } from "@usemarble/sdk/models";

let value: AuthorsListResponse = {
  authors: [
    {
      id: "cryitfjp3456lm06xfpzcgl0",
      name: "John Doe",
      image: "https://media.marblecms.com/avatar.jpg",
      slug: "john-doe",
      bio: "Technical writer and developer",
      role: "Editor",
      socials: [],
      count: {
        posts: 12,
      },
    },
  ],
  pagination: {
    limit: 10,
    currentPage: 1,
    nextPage: 2,
    previousPage: null,
    totalPages: 5,
    totalItems: 42,
  },
};

```

--------------------------------

### Example Usage of GetV1PostsResponse in TypeScript

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/operations/getv1postsresponse.md

Demonstrates how to import and utilize the GetV1PostsResponse model in a TypeScript application. This example shows the structure of the response object, including posts and pagination details.

```typescript
import { GetV1PostsResponse } from "@usemarble/sdk/models/operations";

let value: GetV1PostsResponse = {
  result: {
    posts: [
      {
        id: "cryitfjp5678mn09qrstuvwx",
        slug: "getting-started-with-nextjs",
        title: "Getting Started with Next.js",
        content: "<p>Hello world</p>",
        featured: false,
        coverImage: "https://media.marblecms.com/cover.jpg",
        description: "A beginner's guide to Next.js",
        publishedAt: new Date("2024-01-15T10:00:00Z"),
        updatedAt: new Date("2024-01-16T12:00:00Z"),
        attribution: {
          author: "John Doe",
          url: "https://original-source.com/article",
        },
        authors: [],
        category: {
          id: "cryitfjp1234jl04vdnycek8",
          name: "Technology",
          slug: "technology",
          description: "Tech news and tutorials",
        },
        tags: [
          {
            id: "cryitfjp1234jl04vdnycek8",
            name: "JavaScript",
            slug: "javascript",
            description: "JavaScript tutorials",
          },
        ],
      },
    ],
    pagination: {
      limit: 10,
      currentPage: 1,
      nextPage: 2,
      previousPage: null,
      totalPages: 5,
      totalItems: 42,
    },
  },
};
```

--------------------------------

### Example Usage of AuthorResponse Model (TypeScript)

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/authorresponse.md

Demonstrates how to import and instantiate the AuthorResponse model in TypeScript. This example shows the structure of the data expected for an author, including their ID, name, image, slug, bio, role, social links, and post count.

```typescript
import { AuthorResponse } from "@usemarble/sdk/models";

let value: AuthorResponse = {
  author: {
    id: "cryitfjp3456lm06xfpzcgl0",
    name: "John Doe",
    image: "https://media.marblecms.com/avatar.jpg",
    slug: "john-doe",
    bio: "Technical writer and developer",
    role: "Editor",
    socials: [],
    count: {
      posts: 12,
    },
  },
};
```

--------------------------------

### Instantiate Security Model in TypeScript

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/security.md

Demonstrates how to import and initialize an empty Security object using the Marble TS SDK. This serves as a basic starting point for defining security-related configurations.

```typescript
import { Security } from "@usemarble/sdk/models";

let value: Security = {};
```

--------------------------------

### Fetch Posts with Filtering using Marble SDK (TypeScript)

Source: https://github.com/usemarble/marble-ts/blob/main/USAGE.md

This snippet demonstrates how to initialize the Marble SDK and fetch a list of posts with multiple filtering criteria. It includes options for limiting results, pagination, including/excluding categories and tags, searching by query, specifying format, and filtering by featured posts. The output is iterated through using an async generator.

```typescript
import { Marble } from "@usemarble/sdk";

const marble = new Marble({
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
});

async function run() {
  const result = await marble.posts.list({
    limit: 10,
    page: 1,
    categories: [
      "tech",
      "news",
    ],
    excludeCategories: [
      "changelog",
    ],
    tags: [
      "javascript",
      "react",
    ],
    excludeTags: [
      "outdated",
    ],
    query: "nextjs",
    format: "html",
    featured: "true",
  });

  for await (const page of result) {
    console.log(page);
  }
}

run();

```

--------------------------------

### Initialize Marble SDK with Custom Server URL

Source: https://github.com/usemarble/marble-ts/blob/main/README.md

Demonstrates how to initialize the Marble SDK client with a custom server URL by passing the `serverURL` parameter. This allows you to direct API calls to a specific endpoint. The example also shows a typical usage of the `marble.posts.list` method with various filtering options.

```typescript
import { Marble } from "@usemarble/sdk";

const marble = new Marble({
  serverURL: "https://api.marblecms.com",
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
});

async function run() {
  const result = await marble.posts.list({
    limit: 10,
    page: 1,
    categories: [
      "tech",
      "news",
    ],
    excludeCategories: [
      "changelog",
    ],
    tags: [
      "javascript",
      "react",
    ],
    excludeTags: [
      "outdated",
    ],
    query: "nextjs",
    format: "html",
    featured: "true",
  });

  for await (const page of result) {
    console.log(page);
  }
}

run();

```

--------------------------------

### Instantiate CategoriesListResponse in TypeScript

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/categorieslistresponse.md

Demonstrates how to import and create an instance of the CategoriesListResponse model in TypeScript. This example shows the structure with empty categories and pagination details.

```typescript
import { CategoriesListResponse } from "@usemarble/sdk/models";

let value: CategoriesListResponse = {
  categories: [],
  pagination: {
    limit: 10,
    currentPage: 1,
    nextPage: 2,
    previousPage: null,
    totalPages: 5,
    totalItems: 42,
  },
};
```

--------------------------------

### Example Usage of Marble TS Detail Model

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/detail.md

Demonstrates how to import and instantiate the Detail model in TypeScript. This model is used to represent detailed error or informational messages within the Marble SDK.

```typescript
import { Detail } from "@usemarble/sdk/models";

let value: Detail = {
  field: "limit",
  message: "Expected number, received string",
};
```

--------------------------------

### Instantiate Tag Model in TypeScript

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/tag.md

Demonstrates how to create an instance of the Tag model using TypeScript. This example shows the expected structure for a Tag object, including its ID, name, slug, description, and post count.

```typescript
import { Tag } from "@usemarble/sdk/models";

let value: Tag = {
  id: "cryitfjp4567no07ygqadhm1",
  name: "JavaScript",
  slug: "javascript",
  description: "JavaScript tutorials",
  count: {
    posts: 8,
  },
};
```

--------------------------------

### Import ServerError Model (TypeScript)

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/errors/servererror.md

Demonstrates how to import the ServerError model from the @usemarble/sdk. Currently, no specific usage examples are available for this model.

```typescript
import { ServerError } from "@usemarble/sdk/models/errors";

// No examples available for this model
```

--------------------------------

### Instantiate CategoryResponse in TypeScript

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/categoryresponse.md

Demonstrates how to create an instance of the CategoryResponse model in TypeScript. This requires importing the model from the @usemarble/sdk/models package. The example shows the expected structure for the category object within the response.

```typescript
import { CategoryResponse } from "@usemarble/sdk/models";

let value: CategoryResponse = {
  category: {
    id: "cryitfjp2345kl05weoybfk9",
    name: "Technology",
    slug: "technology",
    description: "Tech news and tutorials",
    count: {
      posts: 15,
    },
  },
};
```

--------------------------------

### Initialize GetV1CategoriesResponse in TypeScript

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/operations/getv1categoriesresponse.md

Demonstrates how to import and initialize the GetV1CategoriesResponse model in TypeScript. This example shows the expected structure for the response, including the nested result object with categories and pagination details.

```typescript
import { GetV1CategoriesResponse } from "@usemarble/sdk/models/operations";

let value: GetV1CategoriesResponse = {
  result: {
    categories: [],
    pagination: {
      limit: 10,
      currentPage: 1,
      nextPage: 2,
      previousPage: null,
      totalPages: 5,
      totalItems: 42,
    },
  },
};
```

--------------------------------

### TypeScript Example Usage of Details Model

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/details.md

Demonstrates how to import and instantiate the Details model in TypeScript. This model is used to represent details about a paginated resource, including a message, total pages, and the requested page number.

```typescript
import { Details } from "@usemarble/sdk/models";

let value: Details = {
  message: "Page 10 does not exist.",
  totalPages: 5,
  requestedPage: 10,
};
```

--------------------------------

### Tags - Get Single Tag (TypeScript)

Source: https://context7.com/usemarble/marble-ts/llms.txt

Retrieves a single tag's details using its ID or slug. It initializes the Marble SDK, calls the `get` method on the `tags` service, and logs the tag's name, slug, description, and total post count.

```typescript
import { Marble } from "@usemarble/sdk";

const marble = new Marble({
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
});

async function getTag() {
  const result = await marble.tags.get({
    identifier: "javascript",
  });

  const tag = result.tag;
  console.log(`Name: ${tag.name}`);
  console.log(`Slug: ${tag.slug}`);
  console.log(`Description: ${tag.description}`);
  console.log(`Total Posts: ${tag.count.posts}`);
}

getTag();
```

--------------------------------

### Instantiate GetV1AuthorsResponse Model in TypeScript

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/operations/getv1authorsresponse.md

Demonstrates how to import and instantiate the GetV1AuthorsResponse model using the Marble TS SDK. This example shows the structure of the response object, including author details and pagination information.

```typescript
import { GetV1AuthorsResponse } from "@usemarble/sdk/models/operations";

let value: GetV1AuthorsResponse = {
  result: {
    authors: [
      {
        id: "cryitfjp3456lm06xfpzcgl0",
        name: "John Doe",
        image: "https://media.marblecms.com/avatar.jpg",
        slug: "john-doe",
        bio: "Technical writer and developer",
        role: "Editor",
        socials: [],
        count: {
          posts: 12,
        },
      },
    ],
    pagination: {
      limit: 10,
      currentPage: 1,
      nextPage: 2,
      previousPage: null,
      totalPages: 5,
      totalItems: 42,
    },
  },
};
```

--------------------------------

### Create Category Object in TypeScript

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/category.md

Demonstrates how to instantiate a Category object using the Marble TS SDK. This example shows the required fields and their expected data types for a valid Category.

```typescript
import { Category } from "@usemarble/sdk/models";

let value: Category = {
  id: "cryitfjp2345kl05weoybfk9",
  name: "Technology",
  slug: "technology",
  description: "Tech news and tutorials",
  count: {
    posts: 15,
  },
};
```

--------------------------------

### GetV1PostsRequest Model

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/operations/getv1postsrequest.md

This section details the structure and example usage of the GetV1PostsRequest model, used for fetching posts with various filtering and sorting options.

```APIDOC
## GetV1PostsRequest

### Description
Represents a request object for fetching posts, allowing filtering by categories, tags, a search query, and specifying the desired format and featured status.

### Method
N/A (This is a model definition, not an endpoint)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **limit** (number) - Optional - The maximum number of posts to return.
- **page** (number) - Optional - The page number for pagination.
- **categories** (string[]) - Optional - An array of category slugs to filter posts by.
- **excludeCategories** (string[]) - Optional - An array of category slugs to exclude posts from.
- **tags** (string[]) - Optional - An array of tag slugs to filter posts by.
- **excludeTags** (string[]) - Optional - An array of tag slugs to exclude posts from.
- **query** (string) - Optional - A search query string to filter posts.
- **format** (string) - Optional - The desired format for the posts (e.g., 'html').
- **featured** (string) - Optional - A flag to filter for featured posts (e.g., 'true').

### Request Example
```typescript
{
  "limit": 10,
  "page": 1,
  "categories": [
    "tech",
    "news"
  ],
  "excludeCategories": [
    "changelog"
  ],
  "tags": [
    "javascript",
    "react"
  ],
  "excludeTags": [
    "outdated"
  ],
  "query": "nextjs",
  "format": "html",
  "featured": "true"
}
```

### Response
#### Success Response (200)
This model does not define a response structure. It is used as a request parameter.

#### Response Example
N/A
```

--------------------------------

### Posts - Get Single Post

Source: https://context7.com/usemarble/marble-ts/llms.txt

Retrieves a single post by its ID or slug, with options to specify content format and status.

```APIDOC
## GET /posts/{identifier}

### Description
Retrieve a single post by its ID or slug. Optionally specify content format (html or markdown) and status filter.

### Method
GET

### Endpoint
/posts/{identifier}

### Path Parameters
- **identifier** (string) - Required - The ID or slug of the post to retrieve.

### Query Parameters
- **format** (string) - Optional - The desired content format ('html' or 'markdown').
- **status** (string) - Optional - Filter by post status ('published', 'draft', etc.).

### Response
#### Success Response (200)
- **post** (object) - The post object containing details like title, content, author, category, tags, etc.

#### Response Example
{
  "post": {
    "id": "post-1",
    "title": "Getting Started with Next.js",
    "slug": "getting-started-with-nextjs",
    "description": "A comprehensive guide to starting your project with Next.js.",
    "content": "<p>This is the HTML content of the post...</p>",
    "featured": false,
    "coverImage": "https://example.com/image.jpg",
    "publishedAt": "2023-10-26T09:00:00Z",
    "updatedAt": "2023-10-27T11:30:00Z",
    "category": {
      "id": "cat-1",
      "name": "Web Development",
      "slug": "web-dev"
    },
    "authors": [
      {
        "id": "author-1",
        "name": "Jane Smith",
        "slug": "jane-smith",
        "role": "Developer"
      }
    ],
    "tags": [
      {
        "id": "tag-1",
        "name": "Next.js",
        "slug": "nextjs"
      },
      {
        "id": "tag-2",
        "name": "React",
        "slug": "react"
      }
    ],
    "attribution": null
  }
}

```

--------------------------------

### Marble CMS Fields

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/post.md

This section details the fields available in the Marble CMS, including their types, whether they are required, and example values.

```APIDOC
## Fields

This documentation outlines the fields available within the Marble CMS.

### Fields Overview

| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| `id` | string | Yes | N/A | cryitfjp5678mn09qrstuvwx |
| `slug` | string | Yes | N/A | getting-started-with-nextjs |
| `title` | string | Yes | N/A | Getting Started with Next.js |
| `content` | string | Yes | N/A | <p>Hello world</p> |
| `featured` | boolean | Yes | N/A | false |
| `coverImage` | string | Yes | N/A | https://media.marblecms.com/cover.jpg |
| `description` | string | Yes | N/A | A beginner's guide to Next.js |
| `publishedAt` | Date | Yes | N/A | 2024-01-15T10:00:00Z |
```

--------------------------------

### Fetch Post by Identifier using Marble SDK (TypeScript)

Source: https://github.com/usemarble/marble-ts/blob/main/docs/sdks/posts/README.md

Demonstrates how to fetch a single post by its identifier using the Marble SDK's class-based approach. It initializes the Marble client with an API key and calls the `get` method on the `posts` service. The output is logged to the console.

```typescript
import { Marble } from "@usemarble/sdk";

const marble = new Marble({
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
});

async function run() {
  const result = await marble.posts.get({
    identifier: "my-post-slug",
    format: "html",
  });

  console.log(result);
}

run();
```

--------------------------------

### Import ErrorT Model (TypeScript)

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/errors/errort.md

Demonstrates how to import the ErrorT model from the Marble TS SDK. This is a foundational step for using the model in your TypeScript projects. No specific usage examples are available at this time.

```typescript
import { ErrorT } from "@usemarble/sdk/models/errors";

// No examples available for this model
```

--------------------------------

### GET /v1/authors

Source: https://github.com/usemarble/marble-ts/blob/main/docs/sdks/authors/README.md

Retrieves a list of authors. This endpoint can be used to get a single author by providing an ID or slug in the request.

```APIDOC
## GET /v1/authors

### Description
Get a single author by ID or slug.

### Method
GET

### Endpoint
/v1/authors

### Parameters
#### Query Parameters
- **request** (operations.GetV1AuthorsRequest) - Required - The request object to use for the request.
- **options** (RequestOptions) - Optional - Used to set various options for making HTTP requests.
  - **options.fetchOptions** (RequestInit) - Optional - Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
  - **options.retries** (RetryConfig) - Optional - Enables retrying HTTP requests under certain failure conditions.

### Response
#### Success Response (200)
- **Promise<operations.GetV1AuthorsResponse>** - The response object containing author information.

#### Error Response
- **errors.ErrorT** (400) - application/json
- **errors.PageNotFoundError** (400) - application/json
- **errors.ServerError** (500) - application/json
- **errors.MarbleDefaultError** (4XX, 5XX) - */*
```

--------------------------------

### Initialize Marble SDK Client

Source: https://context7.com/usemarble/marble-ts/llms.txt

Initializes a new instance of the Marble client using an API key. The API key can be provided directly or via the MARBLE_API_KEY environment variable.

```typescript
import { Marble } from "@usemarble/sdk";

const marble = new Marble({
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
});
```

--------------------------------

### Categories - Get Single Category (TypeScript)

Source: https://context7.com/usemarble/marble-ts/llms.txt

Retrieves a single category's details using its ID or slug. It initializes the Marble SDK, calls the `get` method on the `categories` service, and logs the category's name, slug, description, and total post count.

```typescript
import { Marble } from "@usemarble/sdk";

const marble = new Marble({
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
});

async function getCategory() {
  const result = await marble.categories.get({
    identifier: "technology",
  });

  const category = result.category;
  console.log(`Name: ${category.name}`);
  console.log(`Slug: ${category.slug}`);
  console.log(`Description: ${category.description}`);
  console.log(`Total Posts: ${category.count.posts}`);
}

getCategory();
```

--------------------------------

### Authors - Get Single Author (TypeScript)

Source: https://context7.com/usemarble/marble-ts/llms.txt

Retrieves a single author's details using their ID or slug. It initializes the Marble SDK, calls the `get` method on the `authors` service, and logs the author's name, slug, role, bio, image, post count, and social media links.

```typescript
import { Marble } from "@usemarble/sdk";

const marble = new Marble({
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
});

async function getAuthor() {
  const result = await marble.authors.get({
    identifier: "john-doe",
  });

  const author = result.author;
  console.log(`Name: ${author.name}`);
  console.log(`Slug: ${author.slug}`);
  console.log(`Role: ${author.role}`);
  console.log(`Bio: ${author.bio}`);
  console.log(`Image: ${author.image}`);
  console.log(`Total Posts: ${author.count?.posts}`);

  for (const social of author.socials) {
    console.log(`${social.platform}: ${social.url}`);
  }
}

getAuthor();
```

--------------------------------

### PostsListResponse Model Usage (TypeScript)

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/postslistresponse.md

Demonstrates how to import and instantiate the PostsListResponse model in TypeScript. It shows the structure for posts and pagination, including types and default values.

```typescript
import { PostsListResponse } from "@usemarble/sdk/models";

let value: PostsListResponse = {
  posts: [],
  pagination: {
    limit: 10,
    currentPage: 1,
    nextPage: 2,
    previousPage: null,
    totalPages: 5,
    totalItems: 42,
  },
};
```

--------------------------------

### GET /v1/posts

Source: https://github.com/usemarble/marble-ts/blob/main/docs/sdks/posts/README.md

Retrieves a list of posts. Supports filtering by status and pagination.

```APIDOC
## GET /v1/posts

### Description
Retrieves a list of posts. Supports filtering by status and pagination.

### Method
GET

### Endpoint
/v1/posts

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filters posts by their status (e.g., 'published', 'draft').
- **limit** (number) - Optional - The maximum number of posts to return.
- **offset** (number) - Optional - The number of posts to skip before returning results.

#### Request Body
None

### Response
#### Success Response (200)
- **data** (array) - An array of post objects.
  - **id** (string) - The unique identifier of the post.
  - **title** (string) - The title of the post.
  - **content** (string) - The main content of the post.
  - **status** (string) - The publication status of the post.
  - **createdAt** (string) - The timestamp when the post was created.
  - **updatedAt** (string) - The timestamp when the post was last updated.

#### Response Example
```json
{
  "data": [
    {
      "id": "post_123",
      "title": "My First Post",
      "content": "This is the content of my first post.",
      "status": "published",
      "createdAt": "2023-10-27T10:00:00Z",
      "updatedAt": "2023-10-27T10:00:00Z"
    }
  ]
}
```

### Errors
- **400 Bad Request**: If the request parameters are invalid.
- **404 Not Found**: If the requested resource does not exist.
- **500 Internal Server Error**: If there is a server-side error.
```

--------------------------------

### Instantiate TagRef Model in TypeScript

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/tagref.md

Demonstrates how to import and create an instance of the TagRef model using TypeScript. The TagRef model requires 'id', 'name', 'slug', and 'description' fields.

```typescript
import { TagRef } from "@usemarble/sdk/models";

let value: TagRef = {
  id: "cryitfjp1234jl04vdnycek8",
  name: "JavaScript",
  slug: "javascript",
  description: "JavaScript tutorials",
};
```

--------------------------------

### GET /v1/authors

Source: https://github.com/usemarble/marble-ts/blob/main/docs/sdks/authors/README.md

Retrieves a paginated list of authors who have published posts on the platform.

```APIDOC
## GET /v1/authors

### Description
Retrieves a paginated list of authors who have published posts.

### Method
GET

### Endpoint
/v1/authors

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of authors to return per page.
- **offset** (integer) - Optional - The number of authors to skip before starting to collect the result set.

### Request Example
```json
{
  "limit": 10,
  "offset": 0
}
```

### Response
#### Success Response (200)
- **authors** (array) - A list of author objects.
  - **id** (string) - The unique identifier for the author.
  - **name** (string) - The name of the author.
  - **bio** (string) - A short biography of the author.
  - **profilePictureUrl** (string) - The URL of the author's profile picture.

#### Response Example
```json
{
  "authors": [
    {
      "id": "author-123",
      "name": "Jane Doe",
      "bio": "A passionate writer and blogger.",
      "profilePictureUrl": "https://example.com/images/jane-doe.jpg"
    }
  ]
}
```
```

--------------------------------

### GET /v1/authors/{identifier}

Source: https://github.com/usemarble/marble-ts/blob/main/docs/sdks/authors/README.md

Retrieves information about a specific author using their unique identifier.

```APIDOC
## GET /v1/authors/{identifier}

### Description
Retrieves information about a specific author using their unique identifier.

### Method
GET

### Endpoint
/v1/authors/{identifier}

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The unique identifier of the author.

### Request Example
```json
{
  "identifier": "john-doe"
}
```

### Response
#### Success Response (200)
- **result** (object) - An object containing the author's information.

#### Response Example
```json
{
  "result": {
    "id": "author-123",
    "name": "John Doe",
    "bio": "A renowned author..."
  }
}
```
```

--------------------------------

### GET /v1/posts/{identifier}

Source: https://github.com/usemarble/marble-ts/blob/main/docs/sdks/posts/README.md

Retrieves a specific post by its identifier. Supports different output formats.

```APIDOC
## GET /v1/posts/{identifier}

### Description
Retrieves a specific post using its unique identifier. The response format can be specified.

### Method
GET

### Endpoint
/v1/posts/{identifier}

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The unique slug or ID of the post.

#### Query Parameters
- **format** (string) - Optional - The desired output format (e.g., 'html', 'json'). Defaults to 'json'.

### Request Example
```json
{
  "identifier": "my-post-slug",
  "format": "html"
}
```

### Response
#### Success Response (200)
- **result** (object) - The content of the post in the requested format.

#### Response Example
```json
{
  "result": "<html>...</html>"
}
```
```

--------------------------------

### SocialRef Model Initialization (TypeScript)

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/socialref.md

Demonstrates how to import and initialize a SocialRef object in TypeScript. This object requires a 'url' and 'platform' field.

```typescript
import { SocialRef } from "@usemarble/sdk/models";

let value: SocialRef = {
  url: "https://twitter.com/johndoe",
  platform: "twitter",
};
```

--------------------------------

### Import NotFoundError in TypeScript

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/errors/notfounderror.md

Demonstrates how to import the NotFoundError class from the @usemarble/sdk. Currently, no direct usage examples are available for this model.

```typescript
import { NotFoundError } from "@usemarble/sdk/models/errors";

// No examples available for this model
```

--------------------------------

### GET /v1/categories

Source: https://github.com/usemarble/marble-ts/blob/main/docs/sdks/categories/README.md

Retrieves a list of categories. This endpoint can be used to fetch all categories or filter them based on specific criteria.

```APIDOC
## GET /v1/categories

### Description
Get a single category by ID or slug.

### Method
GET

### Endpoint
/v1/categories

### Parameters
#### Query Parameters
- **request** (operations.GetV1CategoriesRequest) - Required - The request object to use for the request.
- **options** (RequestOptions) - Optional - Used to set various options for making HTTP requests.
  - **fetchOptions** (RequestInit) - Optional - Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
  - **retries** (RetryConfig) - Optional - Enables retrying HTTP requests under certain failure conditions.

### Response
#### Success Response (200)
- **Promise<operations.GetV1CategoriesResponse>** - The response object containing category data.

#### Error Response
- **errors.ErrorT** (400) - application/json
- **errors.PageNotFoundError** (400) - application/json
- **errors.ServerError** (500) - application/json
- **errors.MarbleDefaultError** (4XX, 5XX) - */*

### Request Example
```json
{
  "request": {
    "slug": "example-slug"
  },
  "options": {
    "fetchOptions": {
      "headers": {
        "X-Custom-Header": "value"
      }
    },
    "retries": {
      "attempts": 3
    }
  }
}
```

### Response Example
```json
{
  "categories": [
    {
      "id": 1,
      "name": "Electronics",
      "slug": "electronics"
    }
  ]
}
```
```

--------------------------------

### Error Types

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/errors/getv1authorsbadrequest.md

This section details the supported error types in the API, including their structure and example usage.

```APIDOC
## Supported Types

### `errors.ErrorT`

This error type is returned when there are issues with query parameters or other general validation failures.

#### Description
Represents a general validation error with a list of specific field issues.

#### Request Body
(Not applicable for error responses)

#### Response
##### Success Response (Not applicable)

##### Error Response (e.g., 400 Bad Request)
- **error** (string) - A general description of the error.
- **details** (array) - An array of objects, each detailing a specific field validation issue.
  - **field** (string) - The name of the field that caused the error.
  - **message** (string) - A message explaining the validation failure for the specific field.
- **message** (string) - A top-level message summarizing the validation failure.

#### Response Example
```json
{
  "error": "Invalid query parameters",
  "details": [
    {
      "field": "limit",
      "message": "Expected number, received string"
    }
  ],
  "message": "Validation failed"
}
```

### `errors.PageNotFoundError`

This error type is returned when a requested page number is out of bounds.

#### Description
Represents an error indicating that the requested page does not exist.

#### Request Body
(Not applicable for error responses)

#### Response
##### Success Response (Not applicable)

##### Error Response (e.g., 404 Not Found)
- **error** (string) - A description of the error, typically 'Invalid page number'.
- **details** (object) - An object containing details about the page error.
  - **message** (string) - A message indicating the page does not exist.
  - **totalPages** (number) - The total number of available pages.
  - **requestedPage** (number) - The page number that was requested.

#### Response Example
```json
{
  "error": "Invalid page number",
  "details": {
    "message": "Page 10 does not exist.",
    "totalPages": 5,
    "requestedPage": 10
  }
}
```
```

--------------------------------

### GET /v1/tags

Source: https://github.com/usemarble/marble-ts/blob/main/docs/sdks/tags/README.md

Retrieves a single tag by its ID or slug. This endpoint allows fetching specific tag information based on unique identifiers.

```APIDOC
## GET /v1/tags

### Description
Get a single tag by ID or slug.

### Method
GET

### Endpoint
/v1/tags

### Parameters
#### Query Parameters
- **request** (operations.GetV1TagsRequest) - Required - The request object to use for the request.
- **options** (RequestOptions) - Optional - Used to set various options for making HTTP requests.
  - **options.fetchOptions** (RequestInit) - Optional - Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
  - **options.retries** (RetryConfig) - Optional - Enables retrying HTTP requests under certain failure conditions.

### Response
#### Success Response (200)
- **Promise<operations.GetV1TagsResponse>** - The response object containing tag information.

#### Error Response
- **errors.ErrorT** (400, application/json)
- **errors.PageNotFoundError** (400, application/json)
- **errors.ServerError** (500, application/json)
- **errors.MarbleDefaultError** (4XX, 5XX, */*)
```

--------------------------------

### Tags - List Tags (TypeScript)

Source: https://context7.com/usemarble/marble-ts/llms.txt

Fetches a paginated list of all tags, including their post counts. It initializes the Marble SDK, calls the `list` method on the `tags` service with specified limit and page, and iterates through the results to log tag names, slugs, descriptions, and post counts.

```typescript
import { Marble } from "@usemarble/sdk";

const marble = new Marble({
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
});

async function listTags() {
  const result = await marble.tags.list({
    limit: 10,
    page: 1,
  });

  for await (const page of result) {
    for (const tag of page.tags) {
      console.log(`${tag.name} (${tag.slug})`);
      console.log(`  Description: ${tag.description}`);
      console.log(`  Posts: ${tag.count.posts}`);
    }
  }
}

listTags();
```

--------------------------------

### Instantiate CategoryRef in TypeScript

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/categoryref.md

Demonstrates how to create an instance of the CategoryRef model using TypeScript. This involves importing the model and providing values for its required fields: id, name, slug, and description.

```typescript
import { CategoryRef } from "@usemarble/sdk/models";

let value: CategoryRef = {
  id: "cryitfjp1234jl04vdnycek8",
  name: "Technology",
  slug: "technology",
  description: "Tech news and tutorials",
};
```

--------------------------------

### Tags - Get Single Tag

Source: https://context7.com/usemarble/marble-ts/llms.txt

Retrieve a single tag by its ID or slug. This endpoint provides detailed information for a specific tag.

```APIDOC
## Tags - Get Single Tag

### Description
Retrieve a single tag by its ID or slug.

### Method
GET

### Endpoint
`/tags/{identifier}`

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The ID or slug of the tag to retrieve.

### Request Example
```json
{
  "identifier": "javascript"
}
```

### Response
#### Success Response (200)
- **tag** (object) - Contains the tag's details.
  - **name** (string) - The name of the tag.
  - **slug** (string) - The slug of the tag.
  - **description** (string) - The description of the tag.
  - **count** (object) - Contains counts of related items.
    - **posts** (integer) - The total number of posts associated with this tag.

#### Response Example
```json
{
  "tag": {
    "name": "JavaScript",
    "slug": "javascript",
    "description": "Articles related to JavaScript programming.",
    "count": {
      "posts": 85
    }
  }
}
```
```

--------------------------------

### Tags - List Tags

Source: https://context7.com/usemarble/marble-ts/llms.txt

Get a paginated list of all tags with their post counts. This endpoint is useful for displaying a list of available tags.

```APIDOC
## Tags - List Tags

### Description
Get a paginated list of all tags with their post counts.

### Method
GET

### Endpoint
`/tags`

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of tags to return per page.
- **page** (integer) - Optional - The page number to retrieve.

### Response
#### Success Response (200)
- **tags** (array) - A list of tags.
  - **name** (string) - The name of the tag.
  - **slug** (string) - The slug of the tag.
  - **description** (string) - The description of the tag.
  - **count** (object) - Contains counts of related items.
    - **posts** (integer) - The total number of posts associated with this tag.

#### Response Example
```json
{
  "tags": [
    {
      "name": "JavaScript",
      "slug": "javascript",
      "description": "Articles related to JavaScript programming.",
      "count": {
        "posts": 85
      }
    }
  ]
}
```
```

--------------------------------

### Fetch a List of Posts with Standalone Function - TypeScript

Source: https://github.com/usemarble/marble-ts/blob/main/FUNCTIONS.md

Demonstrates how to use the `postsList` standalone function from the Marble SDK. It shows the import process, instantiation of `MarbleCore`, calling the function with various parameters, and handling the `Result` type for success and error cases. This approach is optimized for tree-shaking.

```typescript
import { MarbleCore } from "@usemarble/sdk/core.js";
import { postsList } from "@usemarble/sdk/funcs/postsList.js";

// Use `MarbleCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const marble = new MarbleCore({ 
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
});

async function run() {
  const res = await postsList(marble, {
    limit: 10,
    page: 1,
    categories: [
      "tech",
      "news",
    ],
    excludeCategories: [
      "changelog",
    ],
    tags: [
      "javascript",
      "react",
    ],
    excludeTags: [
      "outdated",
    ],
    query: "nextjs",
    format: "html",
    featured: "true",
  });
  if (res.ok) {
    const { value: result } = res;
    for await (const page of result) {
    console.log(page);
  }
  } else {
    console.log("postsList failed:", res.error);
  }
}

run();
```

--------------------------------

### Categories - Get Single Category

Source: https://context7.com/usemarble/marble-ts/llms.txt

Retrieve a single category by its ID or slug. This endpoint provides detailed information for a specific category.

```APIDOC
## Categories - Get Single Category

### Description
Retrieve a single category by its ID or slug.

### Method
GET

### Endpoint
`/categories/{identifier}`

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The ID or slug of the category to retrieve.

### Request Example
```json
{
  "identifier": "technology"
}
```

### Response
#### Success Response (200)
- **category** (object) - Contains the category's details.
  - **name** (string) - The name of the category.
  - **slug** (string) - The slug of the category.
  - **description** (string) - The description of the category.
  - **count** (object) - Contains counts of related items.
    - **posts** (integer) - The total number of posts in this category.

#### Response Example
```json
{
  "category": {
    "name": "Technology",
    "slug": "technology",
    "description": "Articles about technology and gadgets.",
    "count": {
      "posts": 120
    }
  }
}
```
```

--------------------------------

### Initialize GetV1TagsResponse in TypeScript

Source: https://github.com/usemarble/marble-ts/blob/main/docs/models/operations/getv1tagsresponse.md

Demonstrates how to import and initialize the GetV1TagsResponse model in TypeScript. This model is part of the @usemarble/sdk and represents the response structure for tag-related operations, including a result object with tags and pagination details.

```typescript
import { GetV1TagsResponse } from "@usemarble/sdk/models/operations";

let value: GetV1TagsResponse = {
  result: {
    tags: [],
    pagination: {
      limit: 10,
      currentPage: 1,
      nextPage: 2,
      previousPage: null,
      totalPages: 5,
      totalItems: 42,
    },
  },
};
```