open-index/open-npm huggingface dataset:
npm package: @garug/gacha
Description: A versatile gacha system library for managing summons and probabilities in your applications
Author: garug
Latest version: 1.0.0-alpha.2

# Garug's Gacha

[![codecov](https://codecov.io/github/garug/gacha/graph/badge.svg?token=7N7YRD1OKA)](https://codecov.io/github/garug/gacha)

## Description

This repository contains a comprehensive Gacha System designed to simulate the mechanics commonly found in many popular mobile and online games. The system allows users to "pull" for items or characters, which are distributed based on predefined probabilities. This project aims to provide a flexible and extensible framework for developers looking to integrate a gacha mechanic into their applications.

## Features

- Configurable Gacha Pools: Easily define different pools with unique data
- Rarity Tiers: Support for multitle rarity tiers with customizable drop rates
- Pity System: Implement a pity system to ensure users receive a high-rarity items after a certain number of pulls
- Statistics: Generate detailed statistics on pulls, including probabilities and user history

## Usage

### Basic Example

```typescript
import { generatePool } from "garug/gacha";

// Define items and their probabilities
const items = [
  { name: "Some item", probability: 0.5 },
  { name: "Another item", probability: 0.5 },
];

// create a pool
const pool = generatePool({ items });

// get a item
const { item } = pool.random();
```

### Defining probabilities

Instead of define a specific probability for each item, you can use rarities

```typescript
const rarities = [
  { name: "common", probability: 0.5 },
  { name: "rare", probability: 0.3 },
  { name: "epic", probability: 0.15 },
  { name: "legendary", probability: 0.05 },
];
```

There are two different ways of rarities usage, define them on each item or group items for each rarity

```typescript
// for each item
const items_a = [
  { name: "Some item", probability: "rare" },
  { name: "Another item", probability: "legendary" },
];

// grouping items
const items_b = {
  rare: [{ name: "Some item" }],
  legendary: [{ name: "Another item" }],
};

// Both are acceptable to create a pool
const pool_a = generatePool({ items: items_a, rarities });
const pool_b = generatePool({ items: items_b, rarities });
const pool_c = generatePool({ items: [...items_a, ...items_b], rarities });
```

> [!TIP]
> Using rarities, take attention to quantity of items for each rarity to have desired output, for example, if you have two rarities (Lets call them `rare` and `common`), rare with `0.1` probability and common with `0.9` probability, rare has just one item and common has ten items
>
> In this scenario, the rare item has `0.1` of probability, while every common item has `0.09` of probability, making a specific common card more difficult to appear than the rare item

### Sorting a Item

After a pool is created, just call `random` function to get a item

```typescript
const item = pool.random();
```

## How to Contribute

1. Fork the project
2. Commit your changes
3. Push to the branch
4. Create a new Pull Request

## License

This project is licensed under the MIT license
npm package: @garuhq/mcp
Description: Garu MCP server — payments for AI agents. PIX, card, boleto.
Author: Garu Pagamentos
Latest version: 0.1.0

# @garuhq/mcp

MCP server for the [Garu](https://garu.com.br) payment gateway. Enables AI agents to create charges, manage customers, and process payments via PIX, credit card, and boleto.

## Install

### Claude Code

```bash
claude mcp add garu -e GARU_API_KEY=sk_live_xxx -- npx -y @garuhq/mcp
```

### Cursor / Windsurf / VS Code

Add to `.cursor/mcp.json`, `.windsurf/mcp.json`, or `.vscode/mcp.json`:

```json
{
  "mcpServers": {
    "garu": {
      "command": "npx",
      "args": ["-y", "@garuhq/mcp"],
      "env": { "GARU_API_KEY": "sk_live_xxx" }
    }
  }
}
```

### Codex

```bash
codex mcp add garu --env GARU_API_KEY=sk_live_xxx -- npx -y @garuhq/mcp
```

## Tools

### Charges (6 tools)

| Tool | Description |
|------|-------------|
| `create_pix_charge` | Create a PIX charge with QR code |
| `create_card_charge` | Create a credit card charge (1-12 installments) |
| `create_boleto_charge` | Create a boleto bancario charge |
| `list_charges` | List charges with pagination and filters |
| `get_charge` | Get charge details by ID |
| `refund_charge` | Refund a charge (full or partial) |

### Customers (5 tools)

| Tool | Description |
|------|-------------|
| `create_customer` | Create a customer linked to your seller account |
| `list_customers` | List customers with search and pagination |
| `get_customer` | Get customer details by ID |
| `update_customer` | Update customer information |
| `delete_customer` | Remove customer from your seller account |

## Resources

- `garu://docs/quickstart` — Getting started guide
- `garu://docs/openapi` — Link to the OpenAPI spec

## Auth

Set the `GARU_API_KEY` environment variable. Get your key at [garu.com.br](https://garu.com.br).

## Development

```bash
npm install
npm test
npm run build
```

## License

MIT