### Start MCP Server (Bash)

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Provides commands to build and run the MCP server using Bun. The server exposes API endpoints as tools for LLM integration. Requires Bun to be installed and the project to be built.

```bash
# Build the server
bun build src/mcp-server.ts --outfile=dist/server.js --target=bun

# Run the server
bun run dist/server.js

# Or run directly with Bun
bun run src/mcp-server.ts
```

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

### Fetch OpenAPI Specification using Bun

Source: https://github.com/sabraman/posiflora-api/blob/main/README.md

This script fetches the latest openapi.json specification from the Posiflora API documentation. It requires Bun and Playwright to be installed as development dependencies.

```bash
bun run fetch-spec
```

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

### Manage Discount Groups API (TypeScript)

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Enables the creation and listing of discount groups for customers. This functionality uses POST for creation and GET for retrieval of discount group information. It requires a pre-configured client object.

```typescript
// Create discount group
const { data, error } = await client.POST("/v1/discount-groups", {
  body: {
    data: {
      type: "discount-groups",
      attributes: {
        name: "Employee Discount",
        discountPercent: 20,
        isDefault: false
      }
    }
  }
});

// List discount groups
const { data: groups } = await client.GET("/v1/discount-groups", {
  params: {
    query: {
      "page[size]": 50
    }
  }
});
```

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

### Customers API - Get Customers List

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Returns a paginated list of customers with extensive filtering options. This endpoint allows for searching, filtering by bonus groups, discount groups, registration dates, and purchase history.

```APIDOC
## GET /v1/customers

### Description
Returns a paginated list of customers with extensive filtering options including search, bonus groups, discount groups, registration dates, and purchase history.

### Method
GET

### Endpoint
/v1/customers

### Parameters
#### Query Parameters
- **search** (string) - Optional - Search term for customer names or other fields.
- **filter[idBonus]** (string) - Optional - Filter by bonus group ID.
- **filter[ordersCount][from]** (integer) - Optional - Minimum number of orders.
- **filter[ordersCount][to]** (integer) - Optional - Maximum number of orders.
- **filter[create][from]** (string) - Optional - Start date for customer creation (YYYY-MM-DD).
- **filter[create][to]** (string) - Optional - End date for customer creation (YYYY-MM-DD).
- **filter[moreBonus]** (number) - Optional - Minimum bonus amount.
- **page[size]** (integer) - Optional - Number of customers per page (default: 20).
- **page[number]** (integer) - Optional - Page number (default: 1).
- **include** (string) - Optional - Comma-separated list of related resources to include (e.g., `source`, `celebrations`, `preferences`).

### Response
#### Success Response (200)
- **data** (array) - An array of customer objects.
  - Each object contains fields like `id`, `type`, `attributes` (including `name`, `phone`, `bonuses`, `ordersCount`, etc.), and `relationships`.

#### Response Example
```json
{
  "data": [
    {
      "id": "customer-uuid-1",
      "type": "customers",
      "attributes": {
        "name": "John Doe",
        "phone": "+11234567890",
        "bonuses": 1500,
        "ordersCount": 10,
        "avgCheck": 50.50
      }
    }
  ],
  "links": {
    "self": "...",
    "next": "..."
  }
}
```
```

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

### Get Categories (TypeScript)

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Retrieves product categories, optionally recursively to include subcategories. Can filter by parent category to get root categories.

```typescript
// Get all categories
const { data, error } = await client.GET("/v1/categories", {
  params: {
    query: {
      recursive: true,
      "filter[parent]": null // Get root categories
    }
  }
});

if (data) {
  data.data.forEach(category => {
    console.log(`${category.attributes.name} (${category.attributes.itemsCount} items)`);
  });
}
```

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

### Get Bonuses Analytics (TypeScript)

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Retrieves analytics for bonus points, separately for accrued and subtracted bonuses over a specified period.

```typescript
// Get bonuses accrued analytics
const { data: accrued } = await client.GET("/v1/orders/analytics/bonuses-accrued", {
  params: {
    query: {
      from: "2024-01-01",
      to: "2024-06-30"
    }
  }
});

// Get bonuses subtracted analytics
const { data: subtracted } = await client.GET("/v1/orders/analytics/bonuses-subtract", {
  params: {
    query: {
      from: "2024-01-01",
      to: "2024-06-30"
    }
  }
});
```

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

### Customers: Get List with TypeScript

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Fetches a paginated list of customers with extensive filtering capabilities. Supports searching by name, filtering by bonus groups, order counts, registration dates, and bonus amounts. It also allows including related data like source, celebrations, and preferences.

```typescript
// Fetch customers with filters
const { data, error } = await client.GET("/v1/customers", {
  params: {
    query: {
      search: "John",
      "filter[idBonus]": "bonus-group-123",
      "filter[ordersCount][from]": 5,
      "filter[ordersCount][to]": 100,
      "filter[create][from]": "2024-01-01",
      "filter[create][to]": "2024-12-31",
      "filter[moreBonus]": 1000,
      "page[size]": 20,
      "page[number]": 1,
      include: ["source", "celebrations", "preferences"]
    }
  }
});

if (data) {
  data.data.forEach(customer => {
    console.log(`${customer.attributes.name}: ${customer.attributes.phone}`);
    console.log(`  Bonuses: ${customer.attributes.bonuses}`);
    console.log(`  Orders: ${customer.attributes.ordersCount}`);
  });
}
```

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

### Manage Bonus Groups API (TypeScript)

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Provides functions to create, retrieve, and view the history of bonus loyalty program groups. It utilizes a client object with POST and GET methods for interacting with the API. Dependencies include the client object configured for API requests.

```typescript
// Create bonus group
const { data, error } = await client.POST("/v1/bonus-groups", {
  body: {
    data: {
      type: "bonus-groups",
      attributes: {
        name: "Gold Members",
        accrualPercent: 10,
        maxPaymentPercent: 50,
        isDefault: false
      }
    }
  }
});

// Get bonus group details
const { data: groupDetails } = await client.GET("/v1/bonus-groups/{id}", {
  params: {
    path: { id: "bonus-group-uuid" }
  }
});

// Get bonus group change history
const { data: history } = await client.GET("/v1/bonus-groups/{id}/history", {
  params: {
    path: { id: "bonus-group-uuid" }
  }
});
```

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

### Customers API - Get Customer by ID

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Retrieves detailed information about a specific customer using their unique ID. This includes their contact details, bonus history, and purchase statistics.

```APIDOC
## GET /v1/customers/{id}

### Description
Retrieves detailed information about a specific customer including bonus history and purchase statistics.

### Method
GET

### Endpoint
/v1/customers/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the customer to retrieve.

#### Query Parameters
- **include** (string) - Optional - Comma-separated list of related resources to include (e.g., `source`, `celebrations`, `preferences`, `bonusGroup`, `discountGroup`).

### Response
#### Success Response (200)
- **data** (object) - The customer object.
  - **id** (string) - The customer's unique identifier.
  - **type** (string) - `customers`.
  - **attributes** (object) - Customer attributes.
    - **name** (string) - The customer's name.
    - **phone** (string) - The customer's phone number.
    - **bonuses** (number) - The total number of bonuses the customer has.
    - **avgCheck** (number) - The average check amount for the customer.
    - **ordersCount** (integer) - The total number of orders placed by the customer.
  - **relationships** (object) - Related resources.

#### Response Example
```json
{
  "data": {
    "id": "customer-uuid-123",
    "type": "customers",
    "attributes": {
      "name": "John Doe",
      "phone": "+1234567890",
      "bonuses": 1500,
      "avgCheck": 50.50,
      "ordersCount": 10,
      "email": "john.doe@example.com"
    },
    "relationships": {
      "bonusGroup": {
        "data": {
          "type": "bonus-groups",
          "id": "bg-123"
        }
      }
    }
  }
}
```
```

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

### Get Bouquets List (TypeScript)

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Retrieves a list of bouquets with options for filtering and including composition details. Returns bouquet data and potential errors.

```typescript
// Get bouquets list
const { data, error } = await client.GET("/v1/bouquets", {
  params: {
    query: {
      "filter[order]": "order-uuid-123",
      include: ["items", "order"]
    }
  }
});

if (data) {
  data.data.forEach(bouquet => {
    console.log(`Bouquet: ${bouquet.attributes.name}`);
    console.log(`  Price: ${bouquet.attributes.price}`);
    console.log(`  Items: ${bouquet.attributes.itemsCount}`);
  });
}
```

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

### Get Inventory Items

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Retrieves a list of inventory items. Supports filtering by category, availability, store, and pricing. Allows searching by name and recursive retrieval. Returns item details including name, SKU, category, and quantity.

```typescript
// Get available inventory items
const { data, error } = await client.GET("/v1/inventory-items", {
  params: {
    query: {
      search: "rose",
      "filter[categories]": ["cat-flowers-123", "cat-premium-456"],
      "filter[available]": true,
      "filter[hasActivePrices]": true,
      "filter[store]": "store-main-789",
      type: "item",
      recursive: true,
      "page[size]": 50
    }
  }
});

if (data) {
  data.data.forEach(item => {
    console.log(`${item.attributes.name} (SKU: ${item.attributes.sku})`);
    console.log(`  Category: ${item.attributes.categoryName}`);
    console.log(`  Available: ${item.attributes.quantity}`);
  });
}
```

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

### Get Customer Bonus History

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Retrieves the bonus transaction history for a specific customer. Requires a customer ID and allows filtering by date and page size. Returns a list of bonus entries with creation date, amount, and reason.

```typescript
// Get customer bonus history
const { data, error } = await client.GET("/v1/customers/{id}/bonus-history", {
  params: {
    path: { id: "customer-uuid-123" },
    query: {
      "page[size]": 50,
      from: "2024-01-01T00:00:00Z"
    }
  }
});

if (data) {
  data.data.forEach(entry => {
    console.log(`${entry.attributes.createdAt}: ${entry.attributes.amount} bonuses`);
    console.log(`  Reason: ${entry.attributes.reason}`);
  });
}
```

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

### Get Orders List

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Retrieves a list of orders with extensive filtering capabilities. Supports filtering by status, date range, customer, store, delivery method, and payment status. Allows inclusion of related data and sorting. Returns order details including number, status, total price, and delivery date.

```typescript
// Get today's orders with filters
const { data, error } = await client.GET("/v1/orders", {
  params: {
    query: {
      "filter[status]": ["new", "in_progress", "ready"],
      "filter[store]": "store-main-789",
      "filter[shipment][from]": "2024-06-01",
      "filter[shipment][to]": "2024-06-30",
      "filter[delivery]": "delivery",
      "filter[paid]": false,
      include: ["customer", "store", "worker", "bouquets"],
      "page[size]": 25,
      sort: "-createdAt"
    }
  }
});

if (data) {
  data.data.forEach(order => {
    console.log(`Order #${order.attributes.number}`);
    console.log(`  Status: ${order.attributes.status}`);
    console.log(`  Total: ${order.attributes.totalPrice}`);
    console.log(`  Delivery: ${order.attributes.deliveryDate}`);
  });
}
```

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

### Customers: Get by ID with TypeScript

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Retrieves detailed information for a specific customer using their unique ID. This endpoint allows for including related data such as source, celebrations, preferences, bonus group, and discount group information to provide a comprehensive customer view.

```typescript
// Get customer details with related data
const { data, error } = await client.GET("/v1/customers/{id}", {
  params: {
    path: { id: "customer-uuid-123" },
    query: {
      include: ["source", "celebrations", "preferences", "bonusGroup", "discountGroup"]
    }
  }
});

if (data) {
  const customer = data.data.attributes;
  console.log(`Name: ${customer.name}`);
  console.log(`Phone: ${customer.phone}`);
  console.log(`Total bonuses: ${customer.bonuses}`);
  console.log(`Average check: ${customer.avgCheck}`);
  console.log(`Total orders: ${customer.ordersCount}`);
}
```

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

### Run MCP Server with Bun

Source: https://github.com/sabraman/posiflora-api/blob/main/README.md

This command executes the built MCP server using the Bun runtime. The server dynamically loads the openapi.json spec and registers API endpoints as tools for LLMs.

```bash
bun run dist/server.js
```

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

### Build MCP Server with Bun

Source: https://github.com/sabraman/posiflora-api/blob/main/README.md

This command builds the MCP server for the Posiflora API, creating a JavaScript file optimized for the Bun runtime. It compiles the TypeScript source file into a distributable JavaScript file.

```bash
bun build src/mcp-server.ts --outfile=dist/server.js --target=bun
```

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

### Get Marginality Analytics (TypeScript)

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Retrieves profit margin analytics for orders within a specified date range and optionally filtered by store.

```typescript
// Get marginality analytics
const { data, error } = await client.GET("/v1/orders/analytics/marginality", {
  params: {
    query: {
      from: "2024-01-01",
      to: "2024-06-30",
      "filter[store]": "store-main-789"
    }
  }
});
```

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

### Generate TypeScript Client with Bun

Source: https://github.com/sabraman/posiflora-api/blob/main/README.md

This command generates a typed TypeScript client for the Posiflora API based on the OpenAPI specification. It uses Bun as the runtime environment.

```bash
bun run generate
```

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

### MCP Server Usage

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Information on how to build, run, and configure the MCP server for LLM integration.

```APIDOC
### Building the MCP Server

```bash
bun build src/mcp-server.ts --outfile=dist/server.js --target=bun
```

### Running the MCP Server

```bash
# Using Bun runtime
bun run dist/server.js

# Or run directly with Bun
bun run src/mcp-server.ts
```

### MCP Server Configuration Example

Configure your LLM client (e.g., Claude) with the following settings:

```json
{
  "mcpServers": {
    "posiflora": {
      "command": "bun",
      "args": ["run", "/path/to/posiflora-api/dist/server.js"],
      "env": {
        "API_URL": "https://demo.posiflora.com/api"
      }
    }
  }
}
```

### Available MCP Tools (Examples)

The MCP server auto-generates tools from the OpenAPI spec. Examples include:

- `createsession` (POST /v1/sessions)
- `refreshsession` (PATCH /v1/sessions)
- `getcustomerslist` (GET /v1/customers)
- `createcustomer` (POST /v1/customers)
- `getcustomer` (GET /v1/customers/{id})
- `updatecustomer` (PATCH /v1/customers/{id})
- `getorderslist` (GET /v1/orders)
- `createorder` (POST /v1/orders)
- `getaction` (GET /v1/inventory-items)

... and over 140 other tools.
```

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

### MCP Server Configuration (JSON)

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Illustrates the JSON configuration for setting up the MCP server within an LLM client like Claude. It specifies the command to run, arguments, and environment variables, including the API URL.

```json
{
  "mcpServers": {
    "posiflora": {
      "command": "bun",
      "args": ["run", "/path/to/posiflora-api/dist/server.js"],
      "env": {
        "API_URL": "https://demo.posiflora.com/api"
      }
    }
  }
}
```

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

### Get Payments List (TypeScript)

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Retrieves a list of payments with various filtering options, including date range, payment method, and store. Supports pagination.

```typescript
// Get payments list
const { data, error } = await client.GET("/v1/payments", {
  params: {
    query: {
      "filter[from]": "2024-06-01",
      "filter[to]": "2024-06-30",
      "filter[store]": "store-main-789",
      "filter[paymentMethod]": "card",
      "page[size]": 100
    }
  }
});
```

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

### Update Posiflora API Client using Bun

Source: https://github.com/sabraman/posiflora-api/blob/main/README.md

This script combines fetching the latest OpenAPI specification and regenerating the TypeScript client. It ensures the client is always up-to-date with the API.

```bash
bun run update
```

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

### Client Generation Scripts

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Scripts for fetching the OpenAPI specification and generating a TypeScript client.

```APIDOC
### Fetch OpenAPI Spec

Fetches the latest OpenAPI specification from the Posiflora documentation site.

```bash
bun run fetch-spec
```

This command executes `scripts/fetch-spec.ts`, which:
1. Launches a headless Chromium browser using Playwright.
2. Navigates to `https://posiflora.com/api/`.
3. Downloads the `openapi.json` file.
4. Saves the file to `./openapi.json`.

### Generate TypeScript Client

Generates TypeScript types from the OpenAPI spec using `openapi-typescript`.

```bash
bun run generate
```

This command executes `scripts/generate.ts`, which:
1. Reads the `./openapi.json` file.
2. Generates TypeScript interfaces.
3. Outputs the generated code to `./src/client.ts`.

### Full Update Workflow

Runs both `fetch-spec` and `generate` to fully update the client.

```bash
bun run update
```

This command is equivalent to:

```bash
bun run fetch-spec && bun run generate
```
```

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

### Get Shipment Revenue Analytics (TypeScript)

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Retrieves shipment revenue analytics for a specified period, with options to filter by store and group results by time period (e.g., month).

```typescript
// Get shipment revenue analytics
const { data, error } = await client.GET("/v1/orders/analytics/shipment-revenue", {
  params: {
    query: {
      from: "2024-01-01",
      to: "2024-06-30",
      "filter[store]": "store-main-789",
      groupBy: "month"
    }
  }
});

if (data) {
  console.log("Revenue by period:");
  data.data.forEach(period => {
    console.log(`  ${period.attributes.period}: ${period.attributes.revenue}`);
  });
}
```

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

### Create Order

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Creates a new order. Requires customer and store associations, along with delivery details (type, date, time, address), recipient information, and optional comments or card text. Returns the number of the newly created order.

```typescript
// Create a new order
const { data, error } = await client.POST("/v1/orders", {
  body: {
    data: {
      type: "orders",
      attributes: {
        deliveryType: "delivery",
        deliveryDate: "2024-06-15",
        deliveryTimeFrom: "14:00",
        deliveryTimeTo: "16:00",
        deliveryAddress: "123 Main Street, Apt 4B",
        recipientName: "John Smith",
        recipientPhone: "+1987654321",
        comment: "Please call before delivery",
        cardText: "Happy Birthday!"
      },
      relationships: {
        customer: {
          data: { type: "customers", id: "customer-uuid-123" }
        },
        store: {
          data: { type: "stores", id: "store-main-789" }
        }
      }
    }
  }
});

if (data) {
  console.log("Created order:", data.data.attributes.number);
}
```

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

### Customers: Create with TypeScript

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Creates a new customer record in the Posiflora system. Requires customer details such as name, phone, email, and optional fields like birthday and comment. It also supports assigning the customer to bonus and discount groups via relationships.

```typescript
// Create a new customer
const { data, error } = await client.POST("/v1/customers", {
  body: {
    data: {
      type: "customers",
      attributes: {
        name: "Jane Doe",
        phone: "+1234567890",
        email: "jane.doe@example.com",
        birthday: "1990-05-15",
        comment: "VIP customer - prefers roses"
      },
      relationships: {
        bonusGroup: {
          data: { type: "bonus-groups", id: "bg-123" }
        },
        discountGroup: {
          data: { type: "discount-groups", id: "dg-456" }
        }
      }
    }
  }
});

if (data) {
  console.log("Created customer ID:", data.data.id);
}
```

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

### Authenticate: Create Session with TypeScript

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Creates a new API session by sending login credentials and returns access and refresh tokens. It utilizes the openapi-fetch library and expects a base URL and path for session creation. The response includes tokens and optionally related worker and role data.

```typescript
import createClient from "openapi-fetch";
import type { paths } from "./client.js";

const client = createClient<paths>({ baseUrl: "https://demo.posiflora.com/api" });

// Create a new session with credentials
const { data, error } = await client.POST("/v1/sessions", {
  body: {
    data: {
      type: "sessions",
      attributes: {
        login: "user@example.com",
        password: "your_password"
      }
    }
  },
  params: {
    query: {
      include: ["worker", "worker.user", "worker.user.roles"]
    }
  }
});

if (error) {
  console.error("Authentication failed:", error);
} else {
  console.log("Access token:", data.data.attributes.accessToken);
  console.log("Refresh token:", data.data.attributes.refreshToken);
}
```

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

### Full Client Update Workflow (Bash)

Source: https://context7.com/sabraman/posiflora-api/llms.txt

A bash command that executes both the fetch-spec and generate scripts to ensure the TypeScript client is fully updated with the latest API definitions. This is a convenient shortcut for the complete update process.

```bash
# Complete update
bun run update

# Equivalent to:
bun run fetch-spec && bun run generate
```

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

### Customers API - Create Customer

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Creates a new customer record with contact information, bonus assignments, and custom attributes. This endpoint is used to onboard new clients into the system.

```APIDOC
## POST /v1/customers

### Description
Creates a new customer record with contact information, bonus assignments, and custom attributes.

### Method
POST

### Endpoint
/v1/customers

### Parameters
#### Request Body
- **data** (object) - Required - The customer data.
  - **type** (string) - Required - Must be `customers`.
  - **attributes** (object) - Required - The customer attributes.
    - **name** (string) - Required - The customer's full name.
    - **phone** (string) - Required - The customer's phone number.
    - **email** (string) - Optional - The customer's email address.
    - **birthday** (string) - Optional - The customer's birthday (YYYY-MM-DD).
    - **comment** (string) - Optional - Any additional notes about the customer.
  - **relationships** (object) - Optional - Relationships to other resources.
    - **bonusGroup** (object) - Optional - The customer's bonus group.
      - **data** (object) - Required if `bonusGroup` is present.
        - **type** (string) - Must be `bonus-groups`.
        - **id** (string) - The ID of the bonus group.
    - **discountGroup** (object) - Optional - The customer's discount group.
      - **data** (object) - Required if `discountGroup` is present.
        - **type** (string) - Must be `discount-groups`.
        - **id** (string) - The ID of the discount group.

### Request Example
```json
{
  "data": {
    "type": "customers",
    "attributes": {
      "name": "Jane Doe",
      "phone": "+1234567890",
      "email": "jane.doe@example.com",
      "birthday": "1990-05-15",
      "comment": "VIP customer - prefers roses"
    },
    "relationships": {
      "bonusGroup": {
        "data": {
          "type": "bonus-groups",
          "id": "bg-123"
        }
      },
      "discountGroup": {
        "data": {
          "type": "discount-groups",
          "id": "dg-456"
        }
      }
    }
  }
}
```

### Response
#### Success Response (201)
- **data** (object) - The created customer object.
  - **id** (string) - The unique identifier for the newly created customer.
  - **type** (string) - `customers`.
  - **attributes** (object) - The attributes of the created customer.

#### Response Example
```json
{
  "data": {
    "id": "customer-uuid-789",
    "type": "customers",
    "attributes": {
      "name": "Jane Doe",
      "phone": "+1234567890",
      "email": "jane.doe@example.com",
      "bonuses": 0,
      "ordersCount": 0
    }
  }
}
```
```

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

### GitHub Actions Workflow for API Update

Source: https://github.com/sabraman/posiflora-api/blob/main/README.md

This YAML configuration defines a GitHub Actions workflow that runs daily to fetch the latest Posiflora API specification, regenerate the TypeScript client, and create a pull request if changes are detected. It automates the process of keeping the API client synchronized.

```yaml
name: Update Posiflora API

on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:

jobs:
  update-api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v1

      - name: Install Dependencies
        run: bun install

      - name: Fetch and Generate API Client
        run: bun run update

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v6
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          commit-message: 'chore: Update Posiflora API client'
          title: 'chore: Update Posiflora API client'
          body: 'This PR updates the Posiflora API client based on the latest OpenAPI specification.'
          branch: update-posiflora-api
          delete-branch: true

```

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

### Create Inventory Item

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Creates a new inventory item. Requires item details such as name, SKU, type, unit, and description. Allows associating the item with a category and vendor. Returns the ID of the newly created item.

```typescript
// Create new inventory item
const { data, error } = await client.POST("/v1/inventory-items", {
  body: {
    data: {
      type: "inventory-items",
      attributes: {
        name: "Red Rose Premium",
        sku: "ROSE-RED-001",
        type: "item",
        unit: "piece",
        description: "Premium long-stem red roses"
      },
      relationships: {
        category: {
          data: { type: "categories", id: "cat-roses-123" }
        },
        vendor: {
          data: { type: "vendors", id: "vendor-farm-456" }
        }
      }
    }
  }
});

if (data) {
  console.log("Created item ID:", data.data.id);
}
```

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

### Discount Groups API

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Endpoints for creating and managing discount groups for customers.

```APIDOC
## POST /v1/discount-groups

### Description
Creates a new discount group.

### Method
POST

### Endpoint
/v1/discount-groups

### Parameters
#### Request Body
- **data** (object) - Required - The payload for creating a discount group.
  - **type** (string) - Required - Must be 'discount-groups'.
  - **attributes** (object) - Required - The attributes of the discount group.
    - **name** (string) - Required - The name of the discount group.
    - **discountPercent** (number) - Required - The percentage of discount.
    - **isDefault** (boolean) - Required - Whether this is the default discount group.

### Request Example
```json
{
  "data": {
    "type": "discount-groups",
    "attributes": {
      "name": "Employee Discount",
      "discountPercent": 20,
      "isDefault": false
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - The created discount group object.

#### Response Example
```json
{
  "data": {
    "type": "discount-groups",
    "id": "discount-group-uuid",
    "attributes": {
      "name": "Employee Discount",
      "discountPercent": 20,
      "isDefault": false
    }
  }
}
```

## GET /v1/discount-groups

### Description
Lists all discount groups.

### Method
GET

### Endpoint
/v1/discount-groups

### Parameters
#### Query Parameters
- **page[size]** (integer) - Optional - The number of discount groups to return per page. Defaults to 20.

### Response
#### Success Response (200)
- **data** (array) - An array of discount group objects.

#### Response Example
```json
{
  "data": [
    {
      "type": "discount-groups",
      "id": "discount-group-uuid-1",
      "attributes": {
        "name": "Employee Discount",
        "discountPercent": 20,
        "isDefault": false
      }
    },
    {
      "type": "discount-groups",
      "id": "discount-group-uuid-2",
      "attributes": {
        "name": "VIP Customers",
        "discountPercent": 15,
        "isDefault": false
      }
    }
  ]
}
```
```

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

### Fetch OpenAPI Spec (Bash)

Source: https://context7.com/sabraman/posiflora-api/llms.txt

A bash script command to fetch the latest OpenAPI specification from the Posiflora documentation site using Playwright. This script automates the download and saving of the openapi.json file.

```bash
# Fetch latest spec
bun run fetch-spec

# This runs scripts/fetch-spec.ts which:
# 1. Launches headless Chromium browser
# 2. Navigates to https://posiflora.com/api/
# 3. Downloads the openapi.json file
# 4. Saves to ./openapi.json
```

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

### POST /v1/orders/{id}/return

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Processes a return for a specified order, including handling refunds and inventory adjustments.

```APIDOC
## POST /v1/orders/{id}/return

### Description
Processes a return for an order, handling refunds and inventory adjustments.

### Method
POST

### Endpoint
/v1/orders/{id}/return

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the order to be returned.

#### Request Body
- **data** (object) - Required - The return data object.
  - **type** (string) - Required - Must be 'returns'.
  - **attributes** (object) - Required - The attributes of the return.
    - **reason** (string) - Required - The reason for the return.
    - **returnAmount** (number) - Required - The amount to be refunded.
    - **returnToInventory** (boolean) - Required - Whether to return items to inventory.

### Request Example
```json
{
  "data": {
    "type": "returns",
    "attributes": {
      "reason": "Customer dissatisfied",
      "returnAmount": 75.00,
      "returnToInventory": true
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - The details of the processed return.
  - **id** (string) - The unique identifier of the return.
  - **type** (string) - The type of the resource, 'returns'.
  - **attributes** (object) - The attributes of the return.
    - **reason** (string) - The reason for the return.
    - **returnAmount** (number) - The amount refunded.
    - **returnToInventory** (boolean) - Indicates if items were returned to inventory.
    - **createdAt** (string) - The timestamp when the return was processed.

#### Response Example
```json
{
  "data": {
    "id": "return-uuid-456",
    "type": "returns",
    "attributes": {
      "reason": "Customer dissatisfied",
      "returnAmount": 75.00,
      "returnToInventory": true,
      "createdAt": "2024-06-15T10:00:00Z"
    }
  }
}
```
```

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

### Categories API

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Endpoint for retrieving product categories.

```APIDOC
## GET /v1/categories

### Description
Retrieves a list of product categories, optionally in a hierarchical structure, and can filter by parent category.

### Method
GET

### Endpoint
/v1/categories

### Parameters
#### Query Parameters
- **recursive** (boolean) - Optional - If true, returns categories in a nested, hierarchical structure.
- **filter[parent]** (string or null) - Optional - Filters categories by their parent ID. Use `null` to get root categories.

### Response
#### Success Response (200)
- **data** (array of objects) - A list of category objects.
  - **id** (string) - The unique identifier of the category.
  - **type** (string) - The type of the resource, 'categories'.
  - **attributes** (object) - The attributes of the category.
    - **name** (string) - The name of the category.
    - **itemsCount** (integer) - The number of items within this category.
    - **children** (array of objects) - Nested categories if `recursive` is true.

#### Response Example
```json
{
  "data": [
    {
      "id": "category-uuid-abc",
      "type": "categories",
      "attributes": {
        "name": "Flowers",
        "itemsCount": 500,
        "children": [
          {
            "id": "category-uuid-def",
            "type": "categories",
            "attributes": {
              "name": "Roses",
              "itemsCount": 150
            }
          }
        ]
      }
    }
  ]
}
```
```

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

### Create Order Payment (TypeScript)

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Creates a payment record for a specific order, including amount, payment method, and date. Returns payment details upon success.

```typescript
// Create payment for order
const { data, error } = await client.POST("/v1/orders/{id}/payments", {
  params: {
    path: { id: "order-uuid-123" }
  },
  body: {
    data: {
      type: "payments",
      attributes: {
        amount: 150.00,
        paymentMethod: "card",
        paymentDate: "2024-06-15T14:30:00Z"
      }
    }
  }
});

if (data) {
  console.log("Payment ID:", data.data.id);
  console.log("Amount:", data.data.attributes.amount);
}
```

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

### Authentication - Create Session

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Creates a new session and returns access and refresh tokens for API authentication. This endpoint is crucial for initiating authenticated requests to the Posiflora API.

```APIDOC
## POST /v1/sessions

### Description
Creates a new session and returns access and refresh tokens for API authentication.

### Method
POST

### Endpoint
/v1/sessions

### Parameters
#### Query Parameters
- **include** (string) - Optional - Comma-separated list of related resources to include in the response (e.g., `worker`, `worker.user`, `worker.user.roles`).

#### Request Body
- **data** (object) - Required - The session data.
  - **type** (string) - Required - Must be `sessions`.
  - **attributes** (object) - Required - The session attributes.
    - **login** (string) - Required - The user's login email.
    - **password** (string) - Required - The user's password.

### Request Example
```json
{
  "data": {
    "type": "sessions",
    "attributes": {
      "login": "user@example.com",
      "password": "your_password"
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - The created session object.
  - **type** (string) - `sessions`.
  - **id** (string) - The session ID.
  - **attributes** (object) - Session attributes.
    - **accessToken** (string) - The access token for authenticated requests.
    - **refreshToken** (string) - The refresh token for obtaining new access tokens.

#### Response Example
```json
{
  "data": {
    "type": "sessions",
    "id": "session-uuid-123",
    "attributes": {
      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "refreshToken": "your_refresh_token_here"
    }
  }
}
```
```

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

### Bonus Groups API

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Endpoints for creating and managing bonus loyalty program groups.

```APIDOC
## POST /v1/bonus-groups

### Description
Creates a new bonus group.

### Method
POST

### Endpoint
/v1/bonus-groups

### Parameters
#### Request Body
- **data** (object) - Required - The payload for creating a bonus group.
  - **type** (string) - Required - Must be 'bonus-groups'.
  - **attributes** (object) - Required - The attributes of the bonus group.
    - **name** (string) - Required - The name of the bonus group.
    - **accrualPercent** (number) - Required - The percentage of points accrued.
    - **maxPaymentPercent** (number) - Required - The maximum percentage of payment that can be made with points.
    - **isDefault** (boolean) - Required - Whether this is the default bonus group.

### Request Example
```json
{
  "data": {
    "type": "bonus-groups",
    "attributes": {
      "name": "Gold Members",
      "accrualPercent": 10,
      "maxPaymentPercent": 50,
      "isDefault": false
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - The created bonus group object.

#### Response Example
```json
{
  "data": {
    "type": "bonus-groups",
    "id": "bonus-group-uuid",
    "attributes": {
      "name": "Gold Members",
      "accrualPercent": 10,
      "maxPaymentPercent": 50,
      "isDefault": false
    }
  }
}
```

## GET /v1/bonus-groups/{id}

### Description
Retrieves the details of a specific bonus group.

### Method
GET

### Endpoint
/v1/bonus-groups/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the bonus group.

### Response
#### Success Response (200)
- **data** (object) - The bonus group object.

#### Response Example
```json
{
  "data": {
    "type": "bonus-groups",
    "id": "bonus-group-uuid",
    "attributes": {
      "name": "Gold Members",
      "accrualPercent": 10,
      "maxPaymentPercent": 50,
      "isDefault": false
    }
  }
}
```

## GET /v1/bonus-groups/{id}/history

### Description
Retrieves the change history for a specific bonus group.

### Method
GET

### Endpoint
/v1/bonus-groups/{id}/history

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the bonus group.

### Response
#### Success Response (200)
- **data** (array) - An array of history records for the bonus group.

#### Response Example
```json
{
  "data": [
    {
      "type": "bonus-group-history",
      "id": "history-record-uuid",
      "attributes": {
        "changedAt": "2023-10-27T10:00:00Z",
        "changedBy": "user-uuid",
        "changes": {
          "name": "Gold Members",
          "accrualPercent": 10
        }
      }
    }
  ]
}
```
```

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

### Process Order Return (TypeScript)

Source: https://context7.com/sabraman/posiflora-api/llms.txt

Processes a return for a given order, including handling refunds and updating inventory. Requires the order ID and return details.

```typescript
// Process order return
const { data, error } = await client.POST("/v1/orders/{id}/return", {
  params: {
    path: { id: "order-uuid-123" }
  },
  body: {
    data: {
      type: "returns",
      attributes: {
        reason: "Customer dissatisfied",
        returnAmount: 75.00,
        returnToInventory: true
      }
    }
  }
});
```