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.
Add this skill
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.