diff --git a/.github/social-preview.png b/.github/social-preview.png new file mode 100644 index 0000000..913929d Binary files /dev/null and b/.github/social-preview.png differ diff --git a/README.md b/README.md index c3cfe2b..d522c30 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,19 @@ -# SeatLayer Java SDK +# SeatLayer Java Server SDK for Reserved Seating [![CI](https://github.com/seatlayer/seatlayer-java/actions/workflows/ci.yml/badge.svg)](https://github.com/seatlayer/seatlayer-java/actions/workflows/ci.yml) [![Maven Central](https://img.shields.io/maven-central/v/io.seatlayer/seatlayer-java.svg)](https://central.sonatype.com/artifact/io.seatlayer/seatlayer-java) [![License: MIT](https://img.shields.io/badge/license-MIT-111827.svg)](LICENSE) -Official Java server SDK for the [SeatLayer](https://seatlayer.io) reserved-seating API. +The official SeatLayer Java server SDK is the **trusted side** of a reserved-seating +integration: inspect the holds a buyer created, price from server data, and book with a +stable `bookingRef`. From Java or Kotlin you manage seating charts, events, sales channels, +and live seat inventory through one typed ticketing API client. + +[SeatLayer artifact on Maven Central](https://central.sonatype.com/artifact/io.seatlayer/seatlayer-java) · +[SeatLayer server SDK documentation](https://docs.seatlayer.io/server-sdk/install/) · +[SeatLayer reserved-seating platform](https://seatlayer.io/) · +[SeatLayer JavaScript seat map SDK](https://www.npmjs.com/package/@seatlayer/js) · +[SeatLayer AI Toolkit](https://github.com/seatlayer/seatlayer-ai-toolkit) > **Server-side only.** This library authenticates with your secret key. Never ship it in an > Android app or anything a ticket buyer can reach — browser and mobile surfaces get short-lived, @@ -16,15 +25,16 @@ Official Java server SDK for the [SeatLayer](https://seatlayer.io) reserved-seat io.seatlayer seatlayer-java - 0.5.0 + 0.6.0 ``` ```groovy -implementation 'io.seatlayer:seatlayer-java:0.5.0' +implementation 'io.seatlayer:seatlayer-java:0.6.0' ``` -Requires Java 17 or newer. **Zero runtime dependencies** — the SDK uses +Published on Maven Central as `io.seatlayer:seatlayer-java`; `0.6.0` is the current release, so no +extra repository declaration is needed. Requires Java 17 or newer. **Zero runtime dependencies** — the SDK uses `java.net.http.HttpClient` and `javax.crypto.Mac` from the JDK plus a small hand-written JSON codec, so it never forces a Jackson or OkHttp version on an application that already has one. @@ -274,6 +284,43 @@ seatlayer.request("POST", "/v1/events/ev_1/some-new-route", null, Map.of("qty", Full reference: [docs.seatlayer.io/server-sdk](https://docs.seatlayer.io/server-sdk/install/) +## Frequently asked questions + +### How do I book seats from Java? + +Add the [`io.seatlayer:seatlayer-java` artifact](https://central.sonatype.com/artifact/io.seatlayer/seatlayer-java), +construct a `SeatLayer` instance with your secret key, and call `inventory().book(...)` with the +hold id and a stable `bookingRef`. When your own backend picks the seats — phone orders, box +office, comps — `inventory().bookBestAvailable(...)` and `inventory().boxOfficeBook(...)` book +outright with no prior hold. A booking reference is required on every booking call, so each sale is +tied to an immutable order id you can reconcile against later. + +### What does the server SDK do that the buyer SDK does not? + +The buyer SDK runs in the browser or mobile app and only **selects and holds** seats. This Java SDK +runs on your trusted server and **inspects and books** them. Your secret key never reaches a buyer +surface: browsers and mobile apps receive short-lived, origin-bound tokens minted here through +`sessions().createManageSession(...)` or `channels().createBuyerAccessSession(...)`. Always price a +sale from `inventory().retrieveHold(...)`, never from values the client sent you. + +### How do temporary seat holds work server-side? + +A hold reserves seats against concurrent buyers for a limited checkout window. From Java you +retrieve it with `inventory().retrieveHold(...)`, whose items and currency are authoritative for +pricing, and confirm it with `inventory().book(...)`. Use `inventory().extendHold(...)` for a long +checkout instead of releasing and re-holding, which would hand the seats to whoever is racing for +them. Booking is a single automatic attempt: after an unknown network outcome you may reconcile and +repeat the exact same event, hold, and `bookingRef` — seats already booked under that reference are +not sold again. + +### Can I use my own payment provider? + +Yes. SeatLayer never processes payment. Charge through Stripe, Adyen, Braintree, or any provider +you already use, calculating the total from the server-inspected hold items rather than from client +input, then call `inventory().book(...)` with your charge or order id as the `bookingRef`. The +[holds and checkout guide](https://docs.seatlayer.io/buyer-sdk/holds-and-checkout/) walks through +the full handoff. + ## Related resources - [Server SDK guide](https://docs.seatlayer.io/server-sdk/install/) @@ -284,23 +331,24 @@ Full reference: [docs.seatlayer.io/server-sdk](https://docs.seatlayer.io/server- - [Agent-readable documentation](https://docs.seatlayer.io/llms.txt) - [SeatLayer GitHub organization](https://github.com/seatlayer) -### Other SeatLayer SDKs +## SeatLayer SDK ecosystem -| Surface | Package | +| Surface | Package or source | |---|---| -| Browser (vanilla) | [`@seatlayer/js`](https://www.npmjs.com/package/@seatlayer/js) | +| JavaScript | [`@seatlayer/js`](https://www.npmjs.com/package/@seatlayer/js) | | React | [`@seatlayer/react`](https://www.npmjs.com/package/@seatlayer/react) | | React Native | [`@seatlayer/react-native`](https://www.npmjs.com/package/@seatlayer/react-native) | | iOS | [`seatlayer-ios`](https://github.com/seatlayer/seatlayer-ios) | -| Android | [`seatlayer-android`](https://github.com/seatlayer/seatlayer-android) | | Flutter | [`seatlayer`](https://pub.dev/packages/seatlayer) | +| Android | [`seatlayer-android`](https://github.com/seatlayer/seatlayer-android) | +| Server SDKs | [Node.js, Python, PHP, Ruby, .NET, Java, and Go](https://docs.seatlayer.io/server-sdk/install/) | | Node.js (server) | [`@seatlayer/server`](https://www.npmjs.com/package/@seatlayer/server) | | Python (server) | [`seatlayer`](https://pypi.org/project/seatlayer/) | | PHP (server) | [`seatlayer/seatlayer-php`](https://packagist.org/packages/seatlayer/seatlayer-php) | -| Java (server) | [`io.seatlayer:seatlayer-java`](https://central.sonatype.com/artifact/io.seatlayer/seatlayer-java) | -| Go (server) | [`github.com/seatlayer/seatlayer-go`](https://pkg.go.dev/github.com/seatlayer/seatlayer-go) | | Ruby (server) | [`seatlayer`](https://rubygems.org/gems/seatlayer) | | .NET (server) | [`SeatLayer`](https://www.nuget.org/packages/SeatLayer) | +| Java (server) | [`io.seatlayer:seatlayer-java`](https://central.sonatype.com/artifact/io.seatlayer/seatlayer-java) (this artifact) | +| Go (server) | [`github.com/seatlayer/seatlayer-go`](https://pkg.go.dev/github.com/seatlayer/seatlayer-go) | ## Development diff --git a/pom.xml b/pom.xml index b75b57a..825d4ab 100644 --- a/pom.xml +++ b/pom.xml @@ -10,7 +10,7 @@ jar SeatLayer Java SDK - Official Java server SDK for the SeatLayer reserved-seating API. + Official Java server SDK for the SeatLayer reserved-seating ticketing API. Server-side only: inspect seat holds, price from server data, book seats with a stable booking reference, and manage seating charts, seat maps, events, sales channels, and live seat inventory from Java or Kotlin. https://seatlayer.io/