CLI gen: detect webhook-shaped sub-objects and emit composite --webhook-* builder
Nobody has claimed this yet.
- Dominant language
- C#
- Stars
- 92
- Forks
- 8
- Avg merge
- 1d 6h
- Merged PRs (30d)
- 4
Description
Part of #338. Depends on gap #1 (per-parameter flags).
Today
Many APIs have a webhook config nested inside the request body:
webhook:
type: object
properties:
url: { type: string, format: uri }
headers: { type: object, additionalProperties: { type: string } }
metadata: { type: object }
events: { type: array, items: { type: string, enum: [...] } }
Per-property flattening (gap #1) skips nested objects today. Firecrawl hand-writes BuildCrawlWebhookAsync / BuildBatchWebhookAsync to compose flags like --webhook-url, --webhook-header k=v, --webhook-metadata k=v, --webhook-event ... into a single webhook struct. ~150 lines, repeated twice with cosmetic differences.
Target
firecrawl crawl https://example.com \
--webhook-url https://my.app/hook \
--webhook-header authorization=Bearer\\ xyz \
--webhook-header x-request-id=abc \
--webhook-metadata customer-id=42 \
--webhook-event completed --webhook-event errored
Proposed approach
- Detection heuristic: a nested object property is webhook-shaped when it has:
- a property of
string/format: uri(any name;url/endpoint/callback/webhookpreferred) - AT LEAST ONE of: a string-map (
headers), a generic-object (metadata), an enum-array (events)
- a property of
- Generate
--<prefix>-*flag set where<prefix>is the property's kebab-cased name (webhook,notification-url, etc.):- URL → single
--<prefix>-url(string) - headers map → repeatable
--<prefix>-header KEY=VALUE(Option<Dictionary<string,string>>with custom parser) - metadata map → repeatable
--<prefix>-metadata KEY=VALUE - events array → repeatable
--<prefix>-eventwithFromAmong(...)for enum constraint
- URL → single
- Composite builder in generated invocation: when
--<prefix>-urlis present, construct the nested object from all--<prefix>-*flags and assign to the request body. - Add helpers to
CliRuntime:ParseKeyValueAsync(IEnumerable<string> tokens) -> Dictionary<string,string>. - Vendor extension
x-cli-webhook: falseto opt out (fall back to nested--<prop>-json).
Acceptance criteria
- Firecrawl
crawlandbatch-scrapeexpose--webhook-url,--webhook-header,--webhook-metadata,--webhook-eventafter regen. - Repeated flags accumulate (
--webhook-header a=1 --webhook-header b=2). - Without any
--webhook-*flag, the webhook field stays unset in the request. - Snapshot test covers an operation with a webhook-shaped property.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing CLI generation for Firecrawl's crawl and batch-scrape operations, then inspect the generated invocation and the CliRuntime helpers. Implement the webhook-shaped flag set and composite assignment described in the issue, including opt-out handling. Regenerate and verify repeated flags, the unset case, and a snapshot test for a webhook-shaped property.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp, openapi
- Domain
- cli, testing, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100