@adland/data 0.14.2 → 0.14.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @adland/data
 
+## 0.14.3
+
+### Patch Changes
+
+- 9296ae2: update tracking system by custom DB & event handling
+
 ## 0.14.2
 
 ### Patch Changes

package/README.md

@@ -1,217 +1,85 @@
 # @adland/data
 
-TypeScript types and Zod schemas for AdLand ad types. Perfect for building forms with react-hook-form, validating data, and type-safe ad handling.
+Type-safe data schemas, validation, and metadata enrichment for [0xSlots](https://0xslots.org) ad types.
 
-## Installation
+## Install
 
 ```bash
 npm install @adland/data
-# or
-pnpm add @adland/data
-# or
-yarn add @adland/data
 ```
 
-## Usage
-
-### TypeScript Types
+## Ad Types
 
-Types are automatically derived from Zod schemas, ensuring type safety:
+| Type | Data | Metadata |
+|------|------|----------|
+| `link` | `{ url }` | title, description, image, icon |
+| `cast` | `{ hash }` | username, pfpUrl, text, timestamp |
+| `miniapp` | `{ url }` | icon, title, description, imageUrl |
+| `token` | `{ address, chainId }` | name, symbol, decimals, logoURI |
+| `farcasterProfile` | `{ fid }` | username, displayName, bio, pfpUrl |
 
-```tsx
-import type { AdData, LinkAd, SwapAd } from "@adland/data";
+## Usage
 
-// Use the types
-const linkAd: LinkAd = {
-  type: "link",
-  url: "https://example.com",
-};
+### Types
 
-const swapAd: SwapAd = {
-  type: "swap",
-  fromToken: "USDC",
-  toToken: "ETH",
-  amount: "100",
-};
+```ts
+import type { AdData, AdType, LinkAd, CastAd } from "@adland/data";
 ```
 
-### Zod Schemas
+### Form Validation
 
-Use Zod schemas for validation and form integration:
+Each ad definition exposes a Zod schema — works directly with form libraries:
 
-```tsx
-import { linkAdSchema, swapAdSchema, validateAdData } from "@adland/data";
-import { useForm } from "react-hook-form";
+```ts
 import { zodResolver } from "@hookform/resolvers/zod";
+import { linkAd } from "@adland/data";
 
-// With react-hook-form
-function MyForm() {
-  const form = useForm({
-    resolver: zodResolver(swapAdSchema),
-  });
-  
-  // ... rest of form
-}
-
-// Direct validation
-const result = validateAdData(someData);
-if (result.success) {
-  console.log("Valid ad data:", result.data);
-} else {
-  console.error("Validation errors:", result.error);
-}
-```
-
-### Combining Schemas
-
-Zod makes it easy to extend and combine schemas:
-
-```tsx
-import { linkAdSchema } from "@adland/data";
-import { z } from "zod";
-
-// Extend a schema
-const customLinkSchema = linkAdSchema.extend({
-  title: z.string(),
-  description: z.string().optional(),
+const form = useForm({
+  resolver: zodResolver(linkAd.data),
 });
-
-// Combine schemas
-const adWithMetadata = z.intersection(
-  linkAdSchema,
-  z.object({ metadata: z.record(z.unknown()) })
-);
 ```
 
-## Ad Types
+### Processing Pipeline
 
-### Link Ad
-Basic link ad type.
+Validate, verify against external sources, and enrich with metadata in one call:
 
-```typescript
-type LinkAd = {
-  type: "link";
-  url: string;
-}
-```
+```ts
+import { linkAd } from "@adland/data";
 
-### Cast Ad
-Farcaster cast link ad type.
+const result = await linkAd.safeProcess({ url: "https://example.com" });
 
-```typescript
-type CastAd = {
-  type: "cast";
-  url: string;
+if (result.success) {
+  console.log(result.data);     // validated input
+  console.log(result.metadata); // { title, description, image, icon }
 }
 ```
 
-### MiniApp Ad
-Farcaster mini app link ad type.
-
-```typescript
-type MiniAppAd = {
-  type: "miniapp";
-  url: string;
-}
-```
+### Registry
 
-### Token Ad
-Token information ad type.
+```ts
+import { ads, getAd, validateAdData } from "@adland/data";
 
-```typescript
-type TokenAd = {
-  type: "token";
-  token: string; // Token address or symbol
-}
+const castDef = getAd("cast");
+const result = validateAdData({ type: "cast", data: { hash: "0x..." } });
 ```
 
-### Swap Ad
-Token swap ad type.
+### Farcaster Utilities
 
-```typescript
-type SwapAd = {
-  type: "swap";
-  fromToken: string; // Token address or symbol
-  toToken: string; // Token address or symbol
-  amount?: string; // Optional amount
-}
-```
+```ts
+import { parseAccountAssociation, FarcasterAPI } from "@adland/data";
 
-## API
+const parsed = parseAccountAssociation(accountAssociation);
+// => { fid, address, type, domain }
+```
 
-### Types
+## How It Works
 
-- `AdType` - Union type of all ad type strings
-- `AdData` - Union type of all ad data objects (discriminated union)
-- `LinkAd` - Link ad type
-- `CastAd` - Cast ad type
-- `MiniAppAd` - MiniApp ad type
-- `TokenAd` - Token ad type
-- `SwapAd` - Swap ad type
-
-### Schemas
-
-- `linkAdSchema` - Zod schema for link ads
-- `castAdSchema` - Zod schema for cast ads
-- `miniappAdSchema` - Zod schema for mini app ads
-- `tokenAdSchema` - Zod schema for token ads
-- `swapAdSchema` - Zod schema for swap ads
-- `adDataSchema` - Discriminated union schema for all ad types
-- `adSchemas` - Object containing all schemas
-- `getAdSchema(type)` - Get schema for a specific ad type
-- `getAllAdSchemas()` - Get all ad schemas
-- `validateAdData(data)` - Validate ad data and return result
-
-## Integration Examples
-
-### React Hook Form
-
-```tsx
-import { useForm } from "react-hook-form";
-import { zodResolver } from "@hookform/resolvers/zod";
-import { swapAdSchema, type SwapAd } from "@adland/data";
-
-function SwapForm() {
-  const form = useForm<SwapAd>({
-    resolver: zodResolver(swapAdSchema),
-    defaultValues: {
-      type: "swap",
-      fromToken: "",
-      toToken: "",
-    },
-  });
-  
-  return (
-    <form onSubmit={form.handleSubmit(onSubmit)}>
-      {/* form fields */}
-    </form>
-  );
-}
-```
+Each ad definition created with `defineAd()` provides:
 
-### Formik
-
-```tsx
-import { Formik } from "formik";
-import { swapAdSchema } from "@adland/data";
-import { toFormikValidationSchema } from "zod-formik-adapter";
-
-function SwapForm() {
-  return (
-    <Formik
-      validationSchema={toFormikValidationSchema(swapAdSchema)}
-      initialValues={{
-        type: "swap" as const,
-        fromToken: "",
-        toToken: "",
-      }}
-      onSubmit={handleSubmit}
-    >
-      {/* form */}
-    </Formik>
-  );
-}
-```
+1. **Zod schema** — runtime data validation
+2. **`verify(data)`** — checks validity against external sources (API, blockchain)
+3. **`getMetadata(data)`** — fetches rich metadata (titles, images, etc.)
+4. **`process(data)` / `safeProcess(data)`** — runs the full pipeline
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adland/data",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "private": false,
   "publishConfig": {
     "access": "public"