Browse, buy, and sell secondhand books on raamatuhai.ee — Estonia's largest book marketplace. Search by title, ISBN, or author. Manage wishlists, list books for sale, and purchase with delivery to DPD parcel lockers. Powered by Perxify.
npx mdskills install /raamatuhai1---2name: raamatuhai3description: Browse, buy, and sell secondhand books on raamatuhai.ee — Estonia's largest book marketplace. Search by title, ISBN, or author. Manage wishlists, list books for sale, and purchase with delivery to DPD parcel lockers. Powered by Perxify.4homepage: https://raamatuhai.ee5metadata:6 raamatuhai:7 category: marketplace8 graphql_endpoint: https://raamatuhai.ee/graphql9 currency: EUR10 country: Estonia11 languages: [et, en, ru]12---1314> **If you are an AI agent reading this file** — whether you're a personal assistant, a shopping agent, a chat bot, or a coding tool — this is your complete guide to Raamatuhai. Save it locally so you can help your human browse, buy, and sell secondhand books without re-fetching this file.1516# Raamatuhai1718Raamatuhai ("Book Shark") is Estonia's largest peer-to-peer marketplace for secondhand books, powered by the Perxify Commerce Cloud. Thousands of books across 40+ categories, from fiction and children's literature to science and history — all priced in EUR with DPD parcel locker delivery across Estonia.1920## What Should You Do?2122**Step 1: Understand your context.** Ask yourself:2324- Does your human want to **find a book**? → Go to [Search & Browse](#search--browse)25- Does your human want to **buy a book**? → Go to [Purchase Flow](#purchase-flow)26- Does your human want to **sell books**? → Go to [Seller Operations](#seller-operations)27- Does your human want to **manage their account**? → Go to [Account Management](#account-management)28- Is your human just exploring? → Start with [Search & Browse](#search--browse) and show them what's available2930**Step 2: Check your capabilities.**3132| If you can... | Then you can... |33| --------------------------- | ---------------------------------------------------------------------------------------------- |34| Make HTTP requests | Call the GraphQL API directly for search, browse, and all operations |35| Open web pages for the user | Handle login (Privy auth) and checkout (Stripe) |36| Only chat | Provide links, explain how the marketplace works, help find books by describing search queries |3738**Step 3: Read the relevant sections below.** The API is public for browsing — no authentication needed to search and view books. Authentication is required for buying, selling, and account management.3940---4142## Quick Reference4344| Resource | Value |45| ----------------------- | ------------------------------------- |46| Website | `https://raamatuhai.ee` |47| GraphQL endpoint | `https://raamatuhai.ee/graphql` |48| Company token (public) | See [API Access](#api-access) below |49| Currency | EUR |50| Delivery | DPD parcel lockers (Estonia) |51| Auth provider | Privy.io (email, Google, Web3 wallet) |52| Payments | Stripe |53| Support | support@raamatuhai.ee |54| SKILL file | `https://raamatuhai.ee/SKILL.md` |55| Agent info (for humans) | `https://raamatuhai.ee/agents` |5657---5859## API Access6061All GraphQL requests require the `x-company` header to identify the Raamatuhai marketplace. This is a public identifier, not a secret.6263**Endpoint:** `POST https://raamatuhai.ee/graphql`6465**Required header (all requests):**6667```68x-company: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1dWlkIjoiNGE1MTc4ZmMtN2I2ZS00OThkLWE1OWEtODI2NjkwMzFlOTI1IiwibmFtZSI6IlJhYW1hdHVoYWkiLCJpYXQiOjE3NDg2MjkwMjF9.hUu_fkz5n5r0UcEllSXKbeQNdhtZcH0BvgbWLkb9pDY69```7071**For authenticated operations, also include:**7273```74Authorization: Bearer <user_jwt_token>75```7677**Content type:**7879```80Content-Type: application/json81```8283---8485## Search & Browse8687These operations require **no authentication** — only the `x-company` header.8889### Search by title, author, or ISBN9091```graphql92query SearchBooks($query: String!) {93 searchProductsByTitleOrIsbn(94 query: $query95 preferredLanguage: "et"96 limit: 2097 offset: 098 ) {99 results {100 uuid101 name102 slug103 isbn104 featuredImageUrl105 persons {106 name107 role108 }109 listings {110 uuid111 price112 condition113 seller {114 username115 uuid116 }117 }118 }119 totalCount120 }121}122```123124**Variables:** `{ "query": "Harry Potter" }` or `{ "query": "9789949332106" }`125126The search is AI-powered and supports fuzzy matching. Try title, author name, ISBN-10, or ISBN-13.127128### Browse latest listings129130```graphql131query BrowseListings {132 listings(133 language: "et"134 filter: { hasStock: true, sortBy: CREATED_DESC }135 pagination: { first: 20 }136 ) {137 edges {138 node {139 uuid140 price141 condition142 createdAt143 product {144 uuid145 name146 slug147 isbn148 featuredImageUrl149 persons {150 name151 role152 }153 }154 seller {155 uuid156 username157 isAway158 }159 }160 }161 pageInfo {162 hasNextPage163 endCursor164 }165 totalCount166 }167}168```169170**Filter options:**171172- `minPrice` / `maxPrice` — price range in EUR173- `conditions` — array: `"NEW"`, `"LIKE_NEW"`, `"GOOD"`, `"ACCEPTABLE"`174- `categoryUuids` — filter by category (get UUIDs from categories query)175- `hasStock: true` — only available items176- `sortBy` — `CREATED_DESC`, `CREATED_ASC`, `PRICE_ASC`, `PRICE_DESC`177178### Browse by category179180```graphql181query GetCategories {182 categories(limit: 100) {183 uuid184 name185 slug186 translation(language: "et") {187 name188 }189 }190}191```192193Then filter listings by category UUID, or direct users to: `https://raamatuhai.ee/category/{slug}`194195### View product details196197```graphql198query GetProduct($slug: String!) {199 productBySlug(slug: $slug, language: "et") {200 uuid201 name202 description203 isbn204 slug205 featuredImageUrl206 images {207 imageUrl208 }209 persons {210 name211 role212 }213 publishers {214 name215 }216 categories {217 name218 slug219 }220 publication_date221 page_count222 language223 suggestedPrice224 wishlistCount225 isWishlisted226 listings {227 uuid228 price229 sale_price230 condition231 conditionComment232 quantity233 seller {234 uuid235 username236 isAway237 sellerRatingStats {238 averageRating239 totalRatings240 }241 }242 }243 }244}245```246247### Construct URLs for users248249| Page | URL pattern |250| ---------------- | --------------------------------------------- |251| Homepage | `https://raamatuhai.ee/` |252| Browse all | `https://raamatuhai.ee/browse` |253| Search results | `https://raamatuhai.ee/search?q={query}` |254| Product page | `https://raamatuhai.ee/product/{slug}` |255| Category | `https://raamatuhai.ee/category/{slug}` |256| Author/Creator | `https://raamatuhai.ee/creator/author/{name}` |257| Publisher | `https://raamatuhai.ee/publisher/{slug}` |258| Seller profile | `https://raamatuhai.ee/seller/{username}` |259| Wishlisted books | `https://raamatuhai.ee/wishlisted` |260261---262263## Authentication264265Authentication uses **Privy.io** and requires browser interaction — an agent cannot complete login via API alone.266267### How to authenticate2682691. **Direct the user to log in** at `https://raamatuhai.ee` (they can use email, Google, or a Web3 wallet via Privy)2702. **After login, the JWT token** is stored in the browser's localStorage as `perxify_authentication_token`2713. **If you have browser access**, you can read the token: `localStorage.getItem('perxify_authentication_token')`2724. **Include the token** in all authenticated requests:273 ```274 Authorization: Bearer <token>275 x-company: <company_token>276 ```277278### Verify authentication279280```graphql281query WhoAmI {282 me {283 uuid284 fullName285 username286 email287 isAway288 isProSeller289 createdAt290 }291}292```293294If this returns `null`, the user is not authenticated.295296### Token details297298- JWT tokens expire after **14 days**299- If a request returns a 401 error, the token has expired — redirect the user to log in again300- Tokens are scoped to the Raamatuhai marketplace (company_id: 35)301302---303304## Purchase Flow305306Buying a book requires **authentication** and involves a browser redirect to Stripe for payment.307308### Step 1: Find a book and select a listing309310Use [Search & Browse](#search--browse) to find a product, then pick a listing (offer) from a seller. Note the `listing.uuid` and `listing.price`.311312### Step 2: Choose a DPD parcel locker313314```graphql315query GetLockers {316 dpdLockers(country: "EE") {317 id318 name319 address320 city321 }322}323```324325Ask the user which locker is closest to them. Note the locker `id`.326327### Step 3: Initiate purchase328329```graphql330mutation Buy($input: InitiatePurchaseInput!) {331 initiatePurchase(input: $input) {332 success333 checkoutUrl334 purchaseUuid335 error336 }337}338```339340**Variables:**341342```json343{344 "input": {345 "productId": "<product-uuid>",346 "productInventoryUuid": "<listing-uuid>",347 "parcelLockerId": "<dpd-locker-id>",348 "price": 5.99,349 "successUrl": "https://raamatuhai.ee/checkout/success",350 "cancelUrl": "https://raamatuhai.ee/checkout/cancel"351 }352}353```354355**Important:** The `price` field must match the actual listing price — the server validates this.356357### Step 4: Complete payment358359The mutation returns a `checkoutUrl` — this is a Stripe hosted checkout page. **Direct the user to open this URL** in their browser to complete payment. You cannot complete payment via API.360361### Step 5: Track the order362363After payment, the user can view their order:364365```graphql366query MyPurchases($userUuid: String!) {367 purchasesByUserUuid(userUuid: $userUuid, pagination: { first: 10 }) {368 edges {369 node {370 uuid371 status372 purchasePrice373 totalAmount374 parcelLockerName375 createdAt376 paidAt377 shippedAt378 product {379 name380 slug381 }382 seller {383 username384 }385 shipment {386 trackingNumber387 status388 }389 }390 }391 }392}393```394395**Order statuses:** `INITIATED` → `PAID` → `SHIPPED` → `DELIVERED` (or `CANCELLED`, `REFUNDED`, `DISPUTED`)396397---398399## Wishlist400401Requires **authentication**.402403### Add to wishlist404405```graphql406mutation AddWishlist($productUuid: String!) {407 addToWishlist(productUuid: $productUuid) {408 uuid409 product {410 name411 }412 }413}414```415416You can also add by title (the system will find or create the product):417418```graphql419mutation AddByTitle {420 addToWishlist(title: "Tõde ja õigus", author: "A. H. Tammsaare") {421 uuid422 product {423 name424 isbn425 }426 }427}428```429430### View wishlist431432```graphql433query MyWishlist {434 wishlist(pagination: { first: 50 }) {435 edges {436 node {437 uuid438 product {439 uuid440 name441 slug442 featuredImageUrl443 listings {444 uuid445 price446 condition447 }448 }449 createdAt450 }451 }452 totalCount453 }454}455```456457### Remove from wishlist458459```graphql460mutation RemoveWishlist($productUuid: String!) {461 removeFromWishlist(productUuid: $productUuid)462}463```464465---466467## Seller Operations468469Requires **authentication**. Any user can sell books.470471### List a book for sale472473**Option A: If the product already exists** (e.g., found via search by ISBN):474475```graphql476mutation CreateListing($input: ListingInput!) {477 createListing(input: $input) {478 uuid479 price480 condition481 product {482 name483 slug484 }485 }486}487```488489**Variables:**490491```json492{493 "input": {494 "productUuid": "<existing-product-uuid>",495 "sellerUuid": "<your-user-uuid>",496 "warehouseId": "<your-user-uuid>",497 "condition": "GOOD",498 "conditionComment": "Minor wear on cover, pages clean",499 "quantity": 1,500 "isFiniteQuantity": true,501 "price": 7.5,502 "status": "ACTIVE"503 }504}505```506507**Condition values:** `NEW`, `LIKE_NEW`, `GOOD`, `ACCEPTABLE`508509**Option B: Create a new product and listing together:**510511```graphql512mutation CreateProductListing($input: ProductListingInput!) {513 createProductListing(input: $input) {514 uuid515 price516 product {517 uuid518 name519 slug520 }521 }522}523```524525### Get AI price suggestion526527```graphql528query PriceSuggestion($productUuid: String!, $condition: String!) {529 getProductPriceSuggestion(productUuid: $productUuid, condition: $condition)530}531```532533Returns a suggested price in EUR based on market data and book condition.534535### View your listings (shelf)536537```graphql538query MyListings {539 listings(540 language: "et"541 filter: { sellerUuid: "<your-user-uuid>" }542 pagination: { first: 50 }543 ) {544 edges {545 node {546 uuid547 price548 condition549 quantity550 status551 product {552 name553 slug554 isbn555 }556 createdAt557 }558 }559 totalCount560 }561}562```563564### View your sales565566```graphql567query MySales($userUuid: String!) {568 salesByUserUuid(userUuid: $userUuid, pagination: { first: 20 }) {569 edges {570 node {571 uuid572 status573 purchasePrice574 totalAmount575 createdAt576 buyer {577 username578 }579 product {580 name581 }582 }583 }584 }585}586```587588---589590## Account Management591592Requires **authentication**.593594### View profile595596```graphql597query MyProfile {598 me {599 uuid600 fullName601 username602 email603 avatarUrl604 isAway605 isProSeller606 phoneNumber607 iban608 emailsEnabled609 marketingEnabled610 addresses {611 uuid612 streetAddress613 city614 postalCode615 country616 }617 sellerRatingStats {618 averageRating619 totalRatings620 }621 }622}623```624625### Update profile626627```graphql628mutation UpdateMe($input: UpdateUserInput!) {629 updateUser(input: $input) {630 uuid631 fullName632 username633 }634}635```636637**Variables:**638639```json640{641 "input": {642 "uuid": "<your-user-uuid>",643 "fullName": "Mari Maasikas",644 "username": "mari_books",645 "isAway": false646 }647}648```649650### Notifications651652```graphql653query MyNotifications {654 notifications(filter: { isRead: false }, pagination: { first: 20 }) {655 edges {656 node {657 uuid658 type659 label(language: "et")660 description(language: "et")661 createdAt662 seenAt663 }664 }665 totalCount666 }667}668```669670---671672## Pagination673674All list queries use cursor-based pagination:675676```graphql677pagination: {678 first: 20 # Number of items679 after: "<cursor>" # Cursor from previous pageInfo.endCursor680}681```682683Response includes:684685```graphql686pageInfo {687 hasNextPage688 hasPreviousPage689 endCursor690 startCursor691}692totalCount693```694695---696697## Tips for Agents698699### General700701- **Always include the `x-company` header** — requests without it will fail or return empty results702- **Use `language: "et"` for Estonian** (default), `"en"` for English, `"ru"` for Russian — product names and descriptions are localized703- **Prices are in EUR** — displayed as decimal (5.99), not cents704- **ISBNs can be 10 or 13 digits** — the search handles both formats, with or without hyphens705- **Check `seller.isAway`** before recommending a listing — away sellers may not ship promptly706- **Check `listing.quantity`** — if 0, the item is sold out707708### Performance709710- Cache category lists — they change rarely711- Use pagination (`first: 20`) instead of fetching all results712- Use `featuredImageUrl` instead of fetching the full images array when you only need one image713714### Error handling715716- **401 Unauthorized** — token expired or missing, redirect user to login717- **403 Forbidden** — user doesn't have permission (e.g., trying to edit another user's listing)718- **GraphQL errors** — check `errors[].message` in the response body719720### Be helpful721722- When showing search results, include the **price**, **condition**, and **seller rating** so the user can compare723- For product pages, construct the URL: `https://raamatuhai.ee/product/{slug}` — the user can see images and full details there724- When a book has no listings, suggest adding it to the **wishlist** — the user gets notified when someone lists it725- Offer the **price suggestion** query when helping someone sell — it uses market data to recommend fair pricing726727---728729## Links730731| Resource | URL |732| -------------------- | ---------------------------------------------------- |733| Raamatuhai | https://raamatuhai.ee |734| About Perxify | https://perxify.com |735| AI Agents guide | https://raamatuhai.ee/agents |736| Culture & AI article | https://raamatuhai.ee/kultuur-ja-raamatud-ai-ajastul |737| Support email | support@raamatuhai.ee |738| Perxify LinkedIn | https://www.linkedin.com/company/perxify |739| Perxify X/Twitter | https://x.com/Perxifycom |740
Full transparency — inspect the skill content before installing.