feat(scoring): add ScoreClient#create!, Client#create_score!, Langfuse.create_score!

[Alan-Marx]

TL;DR

Adds ScoreClient#create! / Client#create_score! / Langfuse.create_score! for synchronous, exception-raising score creation, and fixes a latent bug where the SDK silently treated ingestion-rejected batch events as delivered.

Why

create_score is fire-and-forget: it queues the event and reports nothing about whether it was actually delivered, which matches how this SDK's tracing already works and is the right default for scoring inline from a still-open span. But it's the wrong shape for a standalone score arriving out-of-band — e.g. user feedback landing in a request unrelated to the turn it's scoring — where the caller needs to know whether delivery succeeded in order to decide whether to retry. create_score! bypasses the in-memory queue and the trace-sampling gate, sends immediately, and raises (UnauthorizedError/ApiError) on failure.

While building that, found and fixed a bug in handle_batch_response that affects the whole SDK, not just this new path: Langfuse's ingestion endpoint never returns a 4xx for rejected events — per the endpoint's own spec, "input errors" surface as a 200-series/207 response whose body lists them in an errors array instead. That array is the only real per-event success/failure signal; HTTP status alone can't distinguish a fully accepted batch from a fully rejected one. handle_batch_response previously treated every 200/201/204/207 as unconditional success without ever parsing that array, so a rejected event (e.g. failed validation) was silently reported as delivered. This matters more once create_score! exists, since callers are now relying on "no exception" to mean "delivered" — but it was already wrong for every batch send before this PR.

Checklist

• Has label
• Has linked issue
• Tests added for new behavior
• Docs updated (if user-facing)

Closes #

What changed

• Langfuse::ScoreClient#create!: new synchronous variant of #create — builds the same event, then calls api_client.send_batch([event]) directly instead of enqueueing.
• Langfuse::Client#create_score! and Langfuse.create_score!: flat-API forwarding wrappers, matching this SDK's no-nested-objects convention.
• Extracted the shared validation/normalization/event-building logic (name validation, value normalization, data_type lookup) out of #create and into #build_score_event itself, so #create! doesn't duplicate it.
• Langfuse::ApiClient#handle_batch_response: now calls raise_on_batch_errors, which parses the response body's errors array and raises ApiError summarizing the rejected event(s) if it's non-empty. Extracted parse_response_body (previously inlined in extract_error_message) since both now need it.
• docs/API_REFERENCE.md: documented create_score!.
• CHANGELOG.md: noted under [Unreleased].

Validation

bundle exec rspec
# 1355 examples, 0 failures
# Line Coverage: 96.86% (2376 / 2453)

bundle exec rubocop
# 79 files inspected, no offenses detected

---

Note

Medium Risk
Changes ingestion success semantics for all send_batch callers (queued score flushes can now surface API rejections that were previously ignored at the HTTP layer), though queued paths still swallow exceptions; the new API is intentionally strict for out-of-band scoring.

Overview
Adds create_score! on Langfuse, Client, and ScoreClient for scores that must be delivered synchronously (e.g. late user feedback): it skips the in-memory queue and trace sampling gate, calls ingestion immediately, and raises UnauthorizedError / ApiError on failure—unlike fire-and-forget create_score.

Score event building is consolidated so #create and #create! share build_score_event (name/value validation and normalization).

ApiClient#handle_batch_response now treats Langfuse ingestion correctly: on 200/201/204/207 it inspects the response body’s errors array and raises ApiError when events were rejected, instead of treating every success HTTP status as delivered. parse_response_body is shared with extract_error_message.

^{Reviewed by Cursor Bugbot for commit d48a9a3. Bugbot is set up for automated code reviews on this repo. Configure here.}