Code-Ledger/docs/OPENAPI.yaml at main · Life-Experimentalist/Code-Ledger · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
openapi: 3.1.0
info:
  title: CodeLedger Contracts (Worker + Internal Extension + Handlers)
  description: |
    Contract hub for CodeLedger:
    1) Worker HTTP API (Cloudflare/Hono routes)
    2) Internal extension runtime messaging contracts
    3) Event bus contracts and OAuth postMessage contract
    4) Handler registration and base-class interfaces
    5) Storage key/path conventions

    Keep HTTP routes in sync with `worker/src/index.js` and internal contracts in sync
    with `src/background/service-worker.js`, `src/core/event-bus.js`,
    `src/handlers/_base/*`, and `src/handlers/init.js`.
  version: 1.0.1

servers:
  - url: https://codeledger.vkrishna04.me
    description: Production (worker mounted at root; API paths start with `/api`)
  - url: https://codeledger.vkrishna04.me/api
    description: Production API base (convenience entry; same host)
  - url: http://localhost:8787
    description: Local development worker (run with `wrangler dev`)

tags:
  - name: health
    description: Health and monitoring endpoints
  - name: auth
    description: OAuth flows and callbacks
  - name: app
    description: GitHub App related endpoints (requires App JWT)
  - name: webhook
    description: Incoming webhook receivers
  - name: data
    description: Canonical map hosting and admin endpoints
  - name: misc
    description: Miscellaneous routes (favicon, static assets)

paths:
  $ref: "./openapi/paths/worker.yaml"

components:
  $ref: "./openapi/components.yaml#/components"

x-extension-urls:
  description: |
    Browser extension internal URL params (library.html page, not HTTP endpoints).
    All params use window.history.replaceState — no page reload occurs on change.
  base: chrome-extension://{ext-id}/library/library.html
  params:
    tab:
      values:
        [solutions, analytics, graph, ai-chats, canonical, settings, search]
      description: Active top-level view
    settingsTab:
      values: [general, ai, git, platforms, backups, advanced]
      description: Active settings panel tab (only when tab=settings)
    problem:
      format: "{platformCode}-{titleSlug}"
      example: "lc-two-sum"
      description: Open ProblemModal for this problem id
    q:
      description: Search query (solutions view)
    difficulty:
      values: [Easy, Medium, Hard]
      description: Difficulty filter (solutions view)
    platform:
      values: [leetcode, geeksforgeeks, codeforces]
      description: Platform filter (solutions view)
    language:
      description: Language filter, matches lang.name (solutions view)
    sort:
      values: [newest, oldest, diff-asc, diff-desc, title, platform, tags]
      description: Sort order (solutions view)
    tag:
      description: Tag/topic filter (solutions view)
    section:
      values: [difficulty, language, platform, topic]
      description: Open analytics drill-down panel (only when tab=analytics)
    sectionFilter:
      description: Value for the section filter, e.g. "Python" or "Hard"
    graphLayout:
      values: [layered, circular, force]
      description: Graph layout mode (only when tab=graph)
  examples:
    - url: "library.html?tab=settings&settingsTab=git"
      description: Open settings directly on the Git tab
    - url: "library.html?tab=solutions&difficulty=Hard&platform=leetcode"
      description: Solutions filtered to hard LeetCode problems
    - url: "library.html?tab=solutions&problem=lc-two-sum"
      description: Open Two Sum modal (LeetCode)
    - url: "library.html?tab=analytics&section=language&sectionFilter=Python"
      description: Analytics with Python drill-down panel open
    - url: "library.html?tab=graph&graphLayout=force&problem=lc-two-sum"
      description: Graph in force layout with Two Sum modal open

x-codeledger-internal-contracts:
  events:
    $ref: "./openapi/internal/events.yaml"
  runtimeMessages:
    $ref: "./openapi/internal/runtime-messages.yaml"
  handlers:
    $ref: "./openapi/internal/handlers.yaml"
  storage:
    $ref: "./openapi/internal/storage.yaml"