open-index/open-npm huggingface dataset:
npm package: @riculum/fb-conversions-api
Description: A Package for interacting with the Facebook Conversions API, enabling server-side event tracking and conversion optimization for Facebook Ads and Pixel integration.
Author: Riculum
Latest version: 0.1.4

# Facebook Conversions API

A TypeScript package to interact with the Facebook Conversions API, allowing you to send conversion events from your server directly to Facebook.

## Installation

Install the package via npm:

```npm
npm install @riculum/fb-conversions-api
```

## Setup

- Define Environment Variables: Create a `.env` file in the root of your project and add the following variables:
```dotenv
  FACEBOOK_PIXEL_ID=your_pixel_id
  FACEBOOK_ACCESS_TOKEN=your_access_token
  ```
- Load Environment Variables: Ensure `dotenv` is loaded at the start of your script.

## Usage

To send an event to the Facebook Conversions API, import the package and call the fbEvent function with your desired parameters.

```ts
import 'dotenv/config';
import fbEvent from "@riculum/fb-conversions-api";

// Define the event details
const eventName = 'ViewContent';
const params = {
    event_time: 1731176705,
    action_source: 'website',
    user_data: {
        em: ['fb1a4757f83b74e5a87c1554c8689bab12d09674f9e15db366c3636ab452004c'],
        client_ip_address: '1.2.3.4',
        client_user_agent: 'Mozilla/5.0',
    },
    event_source_url: 'https://example.com/product-page',
    event_id: 'unique-event-id-12345',
};

// Optional test event code for validation in test environments
const testEventCode = 'TESTxxxxx';

const response = await fbEvent(eventName, params, testEventCode);
console.log(response);
```

## Response
The function returns a JSON response from Facebook, which includes the status and any error messages if the request fails.

## More information
[Facebook Conversions API Doku](https://developers.facebook.com/docs/marketing-api/conversions-api)

## Versioning
This project follows [Semantic Versioning](https://semver.org/), which means:

- Major version updates (X.0.0) introduce breaking changes. 
- Minor version updates (0.X.0) add backward-compatible functionality.
- Patch version updates (0.0.X) apply backward-compatible bug fixes.

Version numbers are incremented accordingly with each release, making it easy to manage dependencies.

## License
MIT License
npm package: @riculum/ga4-mp-client
Description: A lightweight, type-safe Google Analytics 4 Measurement Protocol client for Node.js and Next.js server-side tracking.
Latest version: 0.1.0

# @riculum/ga4-mp-client

A small, type-safe Google Analytics 4 (GA4) **Measurement Protocol** client for Node.js and Next.js server-side code.

This package lets you send GA4 events via the Measurement Protocol (`/mp/collect`) and optionally validate payloads via the Debug endpoint (`/debug/mp/collect`).

It is designed for:
- server-side tracking
- Next.js App Router / Server Actions
- clean, minimal APIs without unnecessary abstractions

---

## Installation

```bash
npm install @riculum/ga4-mp-client
```

---

## Requirements

You need a GA4 property with a **Web data stream** and the following credentials:

- **Measurement ID** (e.g. `G-XXXXXXXXXX`)
- **API Secret** (from Measurement Protocol settings)

Set them as environment variables:

```bash
GA4_MEASUREMENT_ID=G-XXXXXXXXXX
GA4_API_SECRET=xxxxxxxxxxxxxxxx
```

---

## Recommended Setup: Create a Global Client

Create the GA4 client once and reuse it everywhere.

For example in Next.js:

### `lib/ga.ts`

```ts
import { createGa4MpClient } from '@riculum/ga4-mp-client'

export const ga = createGa4MpClient({
  measurementId: process.env.GA4_MEASUREMENT_ID!,
  apiSecret: process.env.GA4_API_SECRET!,
  region: 'region1',
})
```

---

## Usage

### Purchase Event

Important notes:
- `purchase` **must** include `transaction_id`
- GA4 calculates revenue from `value`, not from `items[].price`

```ts
import { ga } from '@/lib/ga'

const res = await ga.send({
  event: 'purchase',
  body: { client_id: metadata.google.clientId },
  params: {
    transaction_id: order.id,
    currency: 'CHF',
    value: 20.90,
    items: [
      {
        item_id: '1',
        item_name: 'T-Shirt',
        quantity: 1,
        price: 20.90,
      },
    ],
  },
})

if (!res.ok) {
  console.error('GA4 purchase failed', res.status, res.error)
}
```

---

### Add to Cart Event

```ts
const res = await ga.send({
  event: 'add_to_cart',
  body: { client_id: metadata.google.clientId },
  params: {
    currency: 'CHF',
    value: 20.90,
    items: [
      {
        item_id: '1',
        item_name: 'T-Shirt',
        quantity: 1,
        price: 20.90,
      },
    ],
  },
})
```

---

### Custom Event

```ts
await ga.send({
  event: 'trial_started',
  body: { client_id: metadata.google.clientId },
  params: {
    plan: 'pro',
    source: 'pricing_page',
  },
})
```

---

## Debugging

### Validate Payloads

```ts
await ga.send({
  event: 'purchase',
  body: { client_id: metadata.google.clientId },
  debug: true,
  params: {
    transaction_id: `test-${Date.now()}`,
    currency: 'CHF',
    value: 20.90,
    items: [{ item_id: '1', item_name: 'T-Shirt', quantity: 1, price: 20.90 }],
  },
})
```

---

### GA4 DebugView

```ts
await ga.send({
  event: 'purchase',
  body: { client_id: metadata.google.clientId },
  params: {
    debug_mode: true,
    transaction_id: `test-${Date.now()}`,
    currency: 'USD',
    value: 20.90,
    items: [{ item_id: '1', item_name: 'T-Shirt', quantity: 1, price: 20.90 }],
  },
})
```

---

## License

MIT
npm package: @riculum/ts-errors
Description: Type-safe HTTP error classes for TypeScript projects.
Latest version: 0.1.2

# @riculum/ts-errors

A lightweight, type-safe collection of HTTP error classes for TypeScript and JavaScript projects.

This package provides a consistent way to throw, handle, and serialize HTTP errors across backend applications, APIs, and frameworks like Next.js.

---

## Features

- Typed HTTP error classes for common status codes
- Single `HttpError` base class
- Built-in `statusCode`, `message`, and optional `metadata`
- JSON serialization via `toJSON()`
- ESM-first, works with modern Node.js and frameworks
- Zero runtime dependencies

---

## Installation

```bash
npm install @riculum/ts-errors
```

or

```bash
pnpm add @riculum/ts-errors
```

---

## Basic Usage

### Throwing an error

```ts
import { BadRequestError } from '@riculum/ts-errors'

throw new BadRequestError('Email is required', {
  field: 'email',
})
```

---

## Catching and handling errors

```ts
import { HttpError } from '@riculum/ts-errors'

try {
  // your logic
} catch (err) {
  if (err instanceof HttpError) {
    console.log(err.statusCode)
    console.log(err.message)
    console.log(err.metadata)
  }
}
```

---

## JSON Serialization

All errors extending `HttpError` can be converted to JSON.

### Using `toJSON()`

```ts
import { BadRequestError } from '@riculum/ts-errors'

const err = new BadRequestError('Invalid input', { field: 'email' })

console.log(err.toJSON())
```

Output:

```json
{
  "name": "BadRequestError",
  "message": "Invalid input",
  "statusCode": 400,
  "metadata": {
    "field": "email"
  }
}
```

### Using `JSON.stringify`

```ts
import { BadRequestError } from '@riculum/ts-errors'

const err = new BadRequestError('Invalid input', { field: 'email' })

console.log(JSON.stringify(err))
// internally calls toJSON()
```

---

## Example with Next.js Route Handler

```ts
import { HttpError, UnauthorizedError } from '@riculum/ts-errors'

export async function GET() {
  try {
    const user = null
    if (!user) {
      throw new UnauthorizedError('Authentication required')
    }

    return Response.json({ ok: true })
  } catch (err) {
    if (err instanceof HttpError) {
      return Response.json(err.toJSON(), { status: err.statusCode })
    }

    return Response.json(
      {
        name: 'InternalServerError',
        message: 'Unexpected error',
        statusCode: 500,
      },
      { status: 500 },
    )
  }
}
```

---

## License

MIT