olx-pik-toolkit

Interni CLI i MCP server za upravljanje OLX.ba / PIK.ba shopovima. Jedno jezgro (src/core), dva lica: CLI (src/cli) i MCP server (src/mcp).

Zahtjevi

• Node.js 20.12 ili noviji (ispod toga se .env tiho preskace jer loadEnvFile ne postoji; preflight to obara). Preporuka: 22 LTS.

• Odobren API pristup za shop (Gold ili Platinum + odobrenje OLX/PIK podrske). Provjeri sa olx whoami.

• Za klon koji vrti Telegram bota jos i bun u PATH-u (Telegram plugin njime dize svoj MCP server; sam plugin instaliraju pripremi skripte).

Related MCP server: amazon-mcp

Brzi start

bun install
bun run build
cp .env.example .env     # popuni OLX_TOKEN ili OLX_USERNAME/OLX_PASSWORD
bun dist/cli/index.js whoami

Provjere: bun run test (testovi match logike, bez mreze) i bun run typecheck.

CLI primjeri

# Sigurno (citanje)
bun dist/cli/index.js listings ls --state active --all
bun dist/cli/index.js users profile <username>           # javni profil shopa (paket, ocjene)
bun dist/cli/index.js refresh limits
bun dist/cli/index.js category suggest "golf 7"
bun dist/cli/index.js sponsor price 12345 --type 2 --days 7 --refresh-every 8

# Obnova
bun dist/cli/index.js refresh one 12345
bun dist/cli/index.js refresh all --limit 200            # dry-run
bun dist/cli/index.js refresh all --limit 200 --yes      # izvrsi

# Trosak kredita (uvijek trazi --yes)
bun dist/cli/index.js sponsor apply 12345 --type 2 --days 7 --refresh-every 8 --yes

# Planer izdvajanja: predlog u fajl (ne trosi), pa izvrsenje termina dospjelih danas
bun dist/cli/index.js sponsor plan napravi --budzet 500 --dana 7 --trajanje 7
bun dist/cli/index.js sponsor plan prikazi
bun dist/cli/index.js sponsor plan izvrsi              # probni prikaz
bun dist/cli/index.js sponsor plan izvrsi --yes        # naplacuje

# Slike (URL-ovi i/ili lokalni fajlovi)
bun dist/cli/index.js listings images add 12345 --url https://primjer.com/1.jpg https://primjer.com/2.jpg
bun dist/cli/index.js listings images add 12345 --file ./slika1.jpg ./slika2.jpg
bun dist/cli/index.js listings images main 12345 67890     # postavi glavnu sliku po imageId
bun dist/cli/index.js listings images rm 12345 67890        # obrisi sliku

Napomena o slikama (potvrdjeno uzivo): API prima slike samo kao stvarne fajlove preko multipart/form-data, pod poljem images[]. Ne prihvata image_url. Zato --url prvo preuzme sliku pa je posalje kao fajl, a --file salje lokalni fajl direktno. Oba zavrse isto na POST /listings/:id/image-upload.

Spajanje sa vanjskim katalogom (komanda match)

CLI ima komandu match koja spaja PIK oglase sa artiklima iz vanjskog kataloga (po sifri, pa po slicnosti naslova: IDF Jaccard i trigram Dice, sa normalizacijom dijakritika). Katalog se predaje kao fajl, pa repo ne nosi kredencijale nijednog vanjskog sistema:

bun dist/cli/index.js match --katalog izvoz.csv --out izvjestaj.json
bun dist/cli/index.js match --katalog shopify-izvoz.json --with-sku

Prihvata se CSV sa kolonama sifra, naziv, zaliha, cijena (izvoz iz WooCommerce, ERP-a, Excela) ili JSON (Shopify izvoz sa handle/title/skus/totalInventory/price, ili neutralna imena polja). Prazna zaliha ostaje nepoznata, ne nula, da se ne skrije oglas koji je pun. Logika je u src/core/match.ts i src/core/katalog.ts, pokrivena testovima (bun run test).

Snapshot kategorija i lokacija (statički, bez stalnog dohvatanja)

Kategorije i lokacije se rijetko mijenjaju, pa se jednom povuku u JSON i koriste kao statički MCP resource (olx://categories, olx://locations). Pokreni jednom kad token proradi:

node --env-file=.env dist/cli/index.js category dump      # -> olx-dokumentacija/categories.json
node --env-file=.env dist/cli/index.js location dump      # -> locations.json + locations.csv (lagani index)

category dump uz puni categories.json pravi i lagani categories.csv (index: id, parent_id, level, path, name + zastavice brand/model/has_models/show_condition/fee). CSV se regenerise iz JSON-a i bez API poziva: bun dist/cli/index.js category index.

Zatim commitaj te fajlove. Poslije toga AI/MCP cita kategorije i lokacije iz resursa bez ijednog API poziva:

• olx://categories-index (CSV) za PRONALAZAK kategorije po imenu/path. Lagano, koristi prvo.

• olx://categories (puni JSON) samo kad trebas polja kojih nema u CSV-u.

• olx://locations-index (CSV) za country_id (BiH = 49) i city_id po imenu. Lagano, koristi prvo.

• olx://locations (puni JSON) samo za detalje (lat/lon, zip, state).

Za forme i opcije izabrane kategorije koristi live alat olx_category_attributes <id> (opcije nisu u snapshotu, dolaze iz API-ja). Pojedinacni live upiti su i dalje dostupni (category list/children/get/brands/models, location countries/cities/city).

Jedan klon, jedan klijent, jedan nalog

Ovaj repozitorij se klonira po klijentu. U .env tog klona ide token samo tog naloga:

OLX_TOKEN=token_tog_naloga

Zato u toolkitu nema profila, nema prebacivanja naloga i nema alata koji mijenja nalog u letu. Radnja ne moze zavrsiti na pogresnom klijentu, jer u procesu postoji samo jedan nalog. Za drugog klijenta kloniraj repo ponovo i postavi njegov token.

Ko je klijent ovog klona pise u KLIJENT.md (kopija KLIJENT.primjer.md, u .gitignore): naziv firme, username, glavne kategorije, ton komunikacije, sta bot smije bez pitanja i sta nikad bez potvrde. Brojevi (paket, krediti, kvota obnova) se ne prepisuju tamo, nego citaju sa API-ja.

Kad token istekne: ako su u .env postavljeni OLX_USERNAME i OLX_PASSWORD, toolkit sam obnovi token na prvi 401 i ponovi citanje. Radnje koje trose kredite se posle obnove NE ponavljaju same, nego se javlja da ih treba pokrenuti ponovo, da se nista ne naplati dva puta.

MCP server

bun run build
bun dist/mcp/server.js   # radi preko stdio

Server izlaze admin (puna lista) ili klijent (suzena, bez kataloga, lokacija i analitike konkurenata). Tacan broj alata po profilu mjeri bun run kontekst.

Profil se ne bira samo kroz .env. Klijentsku bot sesiju server prepoznaje sam, po OLX_SESIJA_TIP odnosno po runtime mapi .claude-runtime (postavlja ih scripts/lib/sesija.mjs), i tada tvrdo uzima klijentski profil bez obzira na .env. Posljedica u praksi: goli claude u terminalu klona daje vlasniku pun alat, a musterijin bot ostaje suzen i kad .env kaze admin.

OLX_MCP_PROFILE u .env je drugi sloj i smije samo SUZITI: postavljen na klijent uzima alate i terminalu i admin botu. Da klijentski put stvarno daje suzen profil provjerava bun scripts/provjeri-klon.mjs, i to mjerenjem ishoda, ne citanjem varijable.

Pogon klijenta: dvije sesije, cron, AI runda

Puna mapa sa dijagramima je u olx-dokumentacija/arhitektura.md — nju procitaj prvu. Sazetak:

• Klijentska sesija: Telegram bot klijenta, profil klijent, pravila u runtime/SISTEM-klijent.md. AI pogon bira OLX_KLIJENT_AI u .env (pretplata ili deepseek preko OLX_DEEPSEEK_* varijabli; bez njih se sesija ne pokrece). DeepSeek nema vid, pa za objavu iz fotografije postoji vision proxy: uz OLX_VID_API_KEY u .env server registruje alat olx_opisi_sliku koji sliku opise jeftinim Claude Haiku modelom (desetinka centa po slici) i vrati tekst sesiji. Na pretplati nije potreban i ne registruje se.

• Admin bot sesija (opcion po klonu): vlasnikov privatni Telegram kanal za taj shop, profil admin, uvijek na pretplati, bez Bash-a. Priprema: bun scripts/pripremi-admin-runtime.mjs <bot_token> <tvoj_telegram_id> [id_admin_grupe]. BotFather privacy za admin bota OSTAJE ukljucen (u grupi prima samo mention i reply); za klijentskog bota se privacy GASI.

• Telegram most scripts/telegram-most.mjs [klijent|admin-bot]: jedan dugoziv proces koji sam radi getUpdates i sam salje sendMessage (bez Telegram plugina), drzi sesiju zivom dok se radi. Gasi zivu sesiju (kontekst OSTAJE, --resume je nastavlja) poslije mirovanja (OLX_MOST_IDLE_MIN, default 30 min; admin override OLX_MOST_ADMIN_IDLE_MIN), i gasi je uz BRISANJE konteksta u nocnom rezu (OLX_MOST_RESTART_SAT, default 3h). Nijedna poruka se ne gubi: Telegram offset se pomjera tek kad je poruka upisana u red na disku, a stavka izlazi iz reda tek kad je odgovor poslan.

• Rucna proba sesije bun scripts/pokreni-klijenta.mjs: ista klijentska sesija u ISTOM terminalu, na obje platforme (Windows PowerShell ukljucen); greska se vidi odmah, umjesto po logu mosta. Prije probe ugasi posao sesija (telegram-most.mjs) ako radi, jer dva konzumera na istom bot tokenu daju 409. Telegram plugin zivi u .claude-runtime/plugins/ (po klonu, ne globalno) i instaliraju ga pripremi skripte same.

• Cron poslovi bez modela (nula tokena): snapshot pregleda 02:40, dnevne obnove i jutarnja poruka 07:20, backup stanja 08:10, sedmicni pregled ponedjeljkom 07:40. Vrti ih CLI (posao dnevni, posao sedmicni, posao backup, stats snapshot).

• Backup klijentskog stanja (posao backup): pamcenje, izuzeca, audit trag i snapshoti pregleda idu na privatnu granu po klijentu u odvojenom repou stanja. Tokeni namjerno ne idu. Snapshoti su nezamjenjivi retroaktivno, jer OLX ne daje istorijske preglede. Nadzor sa admin strane: scripts/backup-nadzor.sh (ponedjeljak 09h) javi svaki klon koji kasni.

• AI runda (nedjelja 21h, jednom za cijelu masinu): headless analiza svih klonova iz ~/.olx-klijenti.txt kroz vlasnikovu pretplatu, strogo read-only; izvjestaj ide klijentu u grupu, prijedlozi u .olx-pik/prijedlozi/, odakle ih klijentski bot cita alatom olx_prijedlozi i primjenjuje uz potvrdu (Read nad .olx-pik mu je zabranjen, pa ide kroz alat).

Instalacija svih poslova: macOS scripts/instaliraj-cron.sh (launchd, po klonu; AI runda se instalira rucno jednom, uputa u sablonu), Windows deploy/windows/instaliraj-zadatke.ps1 (Task Scheduler, isti termini). Na Windowsu kredencijali pretplate zive u config diru, pa svaki runtime trazi svoj claude login PRIJE instalacije poslova: u PowerShellu $env:CLAUDE_CONFIG_DIR=".claude-runtime" pa claude login (kad klijentska sesija ide na pretplatu; na DeepSeeku ne treba), i isto sa .claude-runtime-admin za admin bota. Na macOS-u su u Keychainu pa login ne treba.

Potrosnja tokena po klijentu

Svaki klon biljezi vlastitu potrosnju sam od sebe: transkripti sesija nose tacan broj tokena po poruci (ulaz, kes, izlaz, model), odvojeno za klijentsku i admin sesiju. Izvjestaj:

bun run tokeni                    # zadnjih 30 dana, po danu i modelu, sa USD i projekcijom
bun run tokeni -- --od 7          # zadnjih 7 dana
bun run tokeni -- --dan 2026-07-28
bun run tokeni -- --upisi         # spoji zbirove u trajni dnevnik (pokreni sedmicno)
bun run tokeni -- --json          # masinski izlaz za dalju obradu

Transkripti se ciste poslije ~30 dana, pa --upisi cuva dnevne zbirove trajno u .olx-pik/tokeni-dnevnik.jsonl. Cijene modela su na jednom mjestu, scripts/ai-cijene.mjs; model kojeg tamo nema dobija tokene bez dolara, broj se ne izmislja. Izlaz ukljucuje prosjek po aktivnom danu i projekciju na 30 dana, sto je osnova za predikciju troska po klijentu.

Za kolege: kloniranje i dodavanje MCP-a u Claude Code

Repozitorij ima .mcp.json u korijenu, pa Claude Code automatski ponudi olx-pik MCP server kad otvoriš projekat. Token se NE čuva u repou; svako postavlja svoj kroz env varijablu OLX_TOKEN.

Koraci poslije kloniranja:

# 1. Build (dist/ je u .gitignore, pa se mora lokalno izgraditi)
bun install
bun run build

# 2. Postavi svoj token u okruzenje (zamijeni vrijednost svojim tokenom)
export OLX_TOKEN=tvoj_token        # zsh/bash; trajno dodaj u ~/.zshrc ili ~/.bashrc

# 3. Otvori Claude Code u korijenu repozitorija
claude

Windows PowerShell ekvivalenti: copy .env.example .env, $env:OLX_TOKEN="tvoj_token" za tekucu sesiju (trajno: setx OLX_TOKEN "tvoj_token" pa NOV terminal).

Pri prvom otvaranju Claude Code pita da odobriš projektni MCP server olx-pik. Potvrdi, pa provjeri sa /mcp. Server preuzima OLX_BASE_URL iz .mcp.json, a OLX_TOKEN iz .env fajla klona ili iz okruženja procesa.

Alternativa bez .mcp.json (registracija samo za tebe, token ostaje lokalno):

claude mcp add olx-pik -s user \
  -e OLX_TOKEN=tvoj_token \
  -e OLX_BASE_URL=https://api.olx.ba \
  -- node "$(pwd)/dist/mcp/server.js"

PowerShell (jedan red, bez \ nastavaka):

claude mcp add olx-pik -s user -e OLX_TOKEN=tvoj_token -e OLX_BASE_URL=https://api.olx.ba -- node "$PWD/dist/mcp/server.js"

Napomene:

• Bez postavljenog OLX_TOKEN server se podigne, ali API pozivi vraćaju 401/403. Provjeri pristup sa node --env-file=.env dist/cli/index.js whoami ili kroz MCP alat olx_whoami.

• Token nikad ne commitati. .env i pravi tokeni su u .gitignore.

Claude Code skillovi

Repozitorij nosi jedanaest skillova u .claude/skills/ (folder je skriven u file browserima jer pocinje tackom, ali je u gitu):

• olx-novi-klijent: ULAZNA TACKA za postavku novog klijentskog klona na novom racunaru, od kloniranja do zivog bota (.env, Telegram runtime za oba bota, plugin, cron, preflight).

• olx-mcp-setup: postavljanje i koristenje toolkita (token, MCP, CLI, troubleshooting).

• olx-analiza-profila: analiza vlastitog profila i oglasa; analiza konkurenta po username-u.

• pik-olx-kreditni-savjetnik: potrosnja kredita, izdvajanje, cjenovnik, strategija promocije.

• olx-shopovi-snimci: obrada Excel snimaka shopova, sva cetiri PIK paketa (razdvajanje po kantonima, po potrebi i u odvojen fajl po nivou paketa, poredjenje dva snimka, telefon kandidata).

• olx-seo-oglasa: naslov, podnaslov i format opisa; izvjestaj pa primjena tek uz potvrdu.

• olx-klijent-flow: kandidat iz javnih podataka, onboarding sa tokenom, prvi potezi po ROI.

• olx-cron-obnove: raspored obnova i ravnomjerno trosenje kvote (izvrsenje nosi CLI cron).

• olx-objava-artikla: vodjena objava novog oglasa od slike do objave, sa provjerom nacrta.

• olx-serijski-posao: posao kroz mnogo oglasa odjednom, preko podagenata iz .claude/agents/.

• olx-izdanje: zatvaranje posla i pustanje koda u flotu klijenata (verzija, tag, stabilno).

Dolaze automatski sa kloniranjem; nista se ne instalira posebno. Sistemski prompt nosi CLAUDE.md u korijenu (tvrde granice kroz olx-dokumentacija/granice.md), a po sloju se sama ucitavaju i pravila iz .claude/rules/ (paths frontmatter).

Dnevna obnova

Dnevnu obnovu NE radi model: CLI posao dnevni (launchd/Task Scheduler u 07:20) obnovi oglase unutar besplatne kvote po tempu do reseta kvote i posalje jutarnju poruku klijentu, sve za nula tokena. Skill olx-cron-obnove sluzi za razgovor o rasporedu i kvoti, ne za izvrsenje. Izdvajanje i akcijska cijena nikad automatski.

Audit log

Svaka radnja koja mijenja stanje ili trosi kredite upisuje se u .olx-pik/audit.jsonl (jedan JSON po liniji, van gita). Zapis nosi vrijeme, verziju toolkita (version), ime komande ili MCP alata, metodu, putanju, status, trajanje i broj pokusaja, a kod odbijenog troska i to da potvrda nije data. Verzija je tu jer "sta je radjeno i kada" ne pomaze kad se ponasanje promijenilo izmedju dva izdanja: zapis mora reci i kojim kodom je radnja izvrsena. Tijelo zahtjeva se nikad ne zapisuje, jer login nosi lozinku. Citanja se ne biljeze osim ako se postavi OLX_AUDIT_READS=1. Putanja se mijenja kroz OLX_AUDIT_FILE; prazna vrijednost gasi log.

Verzija i izdanja

Verzija sistema stoji u src/core/verzija.ts i vidi se na cetiri mjesta: olx --version, MCP handshake, polje version u audit logu i prva stavka bun scripts/provjeri-klon.mjs. Na kojem je izdanju klon: git describe --tags.

Izdanje se pravi sa bun scripts/izdanje.mjs <broj> (provjeri preduslove, pa bun pm version vrti testove, prepise konstantu i izgradi), nosi anotiran tag vX.Y.Z. Pustanje u flotu je bun scripts/pusti-u-flotu.mjs [--pomjeri-stabilno]: bez zastavice sve je povratno, sa njom se pomjera prekidac stabilno (koji kaze koje izdanje flota vozi) i azurira flota. Cijeli tok vodi skill olx-izdanje. Sta je uslo po izdanju: CHANGELOG.md. Zasto dva taga: olx-dokumentacija/arhitektura.md, sekcija 7.

Zaostaje li ovaj klon: bun scripts/provjeri-izdanje.mjs (isto javi i hook pri pokretanju sesije). Povlacenje jednog klona: bun scripts/azuriraj-ovaj-klon.mjs [--restart], koji pri padu builda ili testova sam vraca klon na prethodno izdanje. Sesija kod ne povlaci sama od sebe.

Podaci klijenata

Onboarding klijenta pise baseline i zapise poteza u klijenti/<ime>/. Taj folder je u .gitignore jer sadrzi podatke klijenata. Token klijenta ide u .env tog klona kao OLX_TOKEN, a kontekst klijenta u KLIJENT.md. Nista od toga ne ide u git.

Izvori znanja (jedan izvor istine, ne duplirati brojeve po skillovima):

• olx-dokumentacija/OLX_PIK_AI_Knowledgebase.md — pravila platforme, paketi, kvote, pretraga.

• olx-dokumentacija/API-INVENTAR.md — svi MCP alati, parametri, rupe u API-ju.

• olx-dokumentacija/PIK-pomoc-korpus/ — 52 zvanicna clanka podrske (pomoc.olx.ba).

• olx-dokumentacija/sta-sistem-radi.md — sta sistem radi, obicnim jezikom i bez imena alata. Pise se rukom i cita minut prije razgovora sa klijentom.

• olx-dokumentacija/mogucnosti.md — potpun tehnicki popis: alati, resursi, CLI komande, zakazani poslovi, postavke, skillovi i podagenti. GENERISAN iz koda, ne uredjuje se rukom.

• olx-dokumentacija/mogucnosti.html — isti sadrzaj kao stranica, sa pretragom i prekidacem profila. GENERISAN iz koda, ne uredjuje se rukom.

Oba generisana fajla pravi bun scripts/popis-mogucnosti.mjs, a bun run test pada kad zaostanu za kodom.

PLAN.md je arhiviran handoff iz faze prije builda; stvarno stanje opisuju README i API-INVENTAR.