{"id":"mrcha0s/r3fto-roblox-sdk","name":"r3fto-roblox-sdk","scope":"mrcha0s","platform":"roblox","description":"R3FTO server SDK for Roblox. Reports developer product receipts from your game server to R3FTO.","version":"0.4.0","latest":"0.4.0","versions":["0.1.0","0.2.0","0.2.1","0.3.0","0.4.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"548399cc5d38bc5ffc333596eb2e42709b816430747eea2c8a85d69311a94ba2","likes":0,"downloads":0,"install":"forest install mrcha0s/r3fto-roblox-sdk","url":"https://forest.dev/p/roblox/mrcha0s/r3fto-roblox-sdk","files":"https://api.forest.dev/ai/package/roblox/mrcha0s/r3fto-roblox-sdk/files","readme":"# R3FTO Roblox SDK (server, Luau) · 0.4.0\n\nA server-only Luau package. Only its optional key panel reaches a player's device, and only when your server opens it\nfor that player. It reports **developer-product receipts** and **R3FTO creator-link references** from a Roblox game\nserver to R3FTO. It observes evidence. It never grants a product, never decides a purchase and never computes a creator\nshare or an earning.\n\nFull guide: <https://r3f.to/docs/roblox>. License: MIT (see `LICENSE`).\n\n## Install\n\nPick one. Each gives you the same `R3FTO` ModuleScript in **ServerScriptService** (never in ReplicatedStorage: the SDK\nmust not reach players' devices). Only the optional key panel's own part (`KeyPanelGui`) is copied to a player's device,\nand only when your server calls `R3FTO.openKeyPanel` for that player.\n\n### A. Roblox Studio: drag and drop\n\n1. Download `R3FTO.rbxm` from the [latest release](https://github.com/R3Fto/roblox-sdk/releases/latest).\n2. In Studio, drag the file onto **ServerScriptService** in the Explorer.\n\n### B. Rojo with Wally\n\n```toml\n# wally.toml\n[server-dependencies]\nR3FTO = \"mrcha0s/r3fto-roblox-sdk@0.4.0\"\n```\n\nRun `wally install`, map `ServerPackages` into ServerScriptService in your Rojo project, then use this line in place of\n`require(ServerScriptService:WaitForChild(\"R3FTO\"))` in your scripts:\n\n```lua\nlocal R3FTO = require(game:GetService(\"ServerScriptService\").ServerPackages.R3FTO)\n```\n\n### C. Rojo with Git\n\n```bash\ngit submodule add https://github.com/R3Fto/roblox-sdk.git vendor/r3fto-roblox-sdk\ngit -C vendor/r3fto-roblox-sdk checkout v0.4.0\n```\n\n```json\n\"ServerScriptService\": {\n  \"$className\": \"ServerScriptService\",\n  \"R3FTO\": { \"$path\": \"vendor/r3fto-roblox-sdk/src/R3FTO\" }\n}\n```\n\n### D. By hand\n\nCreate these objects in Roblox Studio (names must match exactly) and paste each file into the object of the same name:\n\n```text\nServerScriptService\n└── R3FTO              ModuleScript  ← src/R3FTO/init.luau\n    ├── Client         ModuleScript  ← src/R3FTO/Client.luau\n    ├── Engine         ModuleScript  ← src/R3FTO/Engine.luau\n    ├── RobloxAdapters ModuleScript  ← src/R3FTO/RobloxAdapters.luau\n    ├── Version        ModuleScript  ← src/R3FTO/Version.luau\n    ├── Wire           ModuleScript  ← src/R3FTO/Wire.luau\n    └── KeyPanelGui    Folder\n        ├── Look       ModuleScript  ← src/R3FTO/KeyPanelGui/Look.luau\n        └── Panel      LocalScript   ← src/R3FTO/KeyPanelGui/Panel.client.luau\n```\n\n### Then, for every install\n\n- Turn on **Allow HTTP Requests** (Experience Settings › Security).\n- Store the SDK token from your game's Roblox tab on R3FTO (one for Test, one for Production; show or copy it there) as the\n  secret `R3FTO_SDK_TOKEN` with domain `r3f.to`: Creator Hub › Secrets for live servers, and Experience Settings ›\n  Security › **Local Secrets** for Studio.\n\nA working game is in `examples/minimal-developer-product/`.\n\n## API\n\n```lua\nlocal R3FTO = require(game:GetService(\"ServerScriptService\"):WaitForChild(\"R3FTO\"))\n\nR3FTO.start({ environment = \"test\" })            -- once, from one server Script; \"production\" with the Production token\n\n-- inside YOUR receipt handler, before your own grant code:\npcall(R3FTO.observeReceipt, receiptInfo)\n\nR3FTO.simulateTestReceipt({ userId = 1, productId = 2, currencySpent = 25, simulationId = \"demo-1\" })  -- Test only\nR3FTO.getReceiptStatus(purchaseId)               -- this server's view of one receipt\nR3FTO.getDiagnostics()                           -- safe to print: no token, no PlayerId, no creator key\nR3FTO.openKeyPanel(player)                       -- optional: the R3FTO Key panel for one player\n```\n\n`start` options:\n\n| Option | Default | Notes |\n|---|---|---|\n| `environment` | none (required) | `\"test\"` or `\"production\"`. Must match the token's environment; R3FTO refuses a mismatch. |\n| `tokenSecretName` | `\"R3FTO_SDK_TOKEN\"` | The secret name. The SDK reads it with `HttpService:GetSecret`; no script can read its value. |\n| `apiBaseUrl` | `\"https://r3f.to\"` | An https origin. |\n| `quiet` | `false` | Hides the `[R3FTO]` info lines; warnings still print. |\n\n`observeReceipt` returns `{ accepted, purchaseId, firstObservedAtUtc, duplicate, queuedUntilStart?, reason? }` at once.\nIt does no I/O itself: the work starts after your handler returns (`task.defer`). Calls made before `start` are kept,\nwith their own observation time, and sent when `start` runs.\n\n**Your handler stays the only handler.** The SDK never sets `MarketplaceService.ProcessReceipt` and never calls\n`BindReceiptHandler`. If you use `BindReceiptHandler`, add the same `pcall(R3FTO.observeReceipt, receiptInfo)` line\ninside your bound handler. You still grant the product and return the decision. An R3FTO or DataStore-copy failure never\nchanges that decision.\n\n## What happens to a receipt\n\n1. `observeReceipt` takes the first observation time (`DateTime.now()`, UTC, milliseconds) before anything that can\n   yield, and checks the receipt fields.\n2. **DataStore copy.** `UpdateAsync` on DataStore `R3FTO_Receipts_v1`, scope `test`|`production`, key = PurchaseId,\n   tagged with the buyer's UserId. If a record already exists (written earlier, maybe by another server), it is kept\n   unchanged and its `firstObservedAtUtc` becomes the one this server reports. The transform makes no network call.\n3. **Direct delivery.** `POST {apiBaseUrl}/v1/roblox-sdk/receipts` with `Authorization: Bearer <secret>`. R3FTO answers\n   `200` only after its PostgreSQL commit. A repeat of the same PurchaseId answers `already_recorded` and is never\n   counted twice.\n4. **Retries.** Each channel makes its first attempt immediately. Retries follow at 60, 180 and 300 seconds after\n   that channel's first attempt, four attempts at most per channel. A channel that succeeds stops. A request R3FTO\n   rejects (4xx other than 408/425/429) is not retried. `Retry-After` can only skip a scheduled attempt, never add one.\n   A repeated callback on the same server joins the running work and never restarts the schedule. A player arrival\n   (see Creator links) retries longer: at 60, 180, 300, 600, 900, 1800 and 3600 seconds, eight attempts at most.\n\nDurability (`getReceiptStatus(...).durability`):\n\n| Value | Meaning |\n|---|---|\n| `delivered` | R3FTO committed it to PostgreSQL. |\n| `stored_awaiting_delivery` | The DataStore copy exists; R3FTO has not acknowledged it yet. |\n| `memory_only` | No durable copy yet. Attempts remain. |\n| `not_durable` | Every attempt ended with no durable copy. If this server stops, the receipt evidence is lost. |\n\nPer channel: `state` is `pending`, `in_progress`, `retry_scheduled`, `succeeded`, `failed` (all attempts used) or\n`rejected`. `lastError` is `storage_failed`, `transport_failed`, `ambiguous` (a timeout: R3FTO may or may not have it;\nthe same PurchaseId is retried), `throttled`, `rejected` or `not_configured` (the SDK token secret is not available on\nthis server, so nothing was sent).\n\n## Creator links\n\nA creator link brings a player into your experience with `r3f_` and the creator's R3FTO key in its launch data (for\nexample `r3f_KAEL`). You never create these links and need no code for them: after `start`, the SDK reads the launch\ndata of every player who joins.\n\n- **Every join counts.** Each join that carries a creator link value is reported once with the server-seen UserId, also\n  when the player comes back with the same value or with another creator's. The same join is never reported twice.\n- **What.** `POST {apiBaseUrl}/v1/roblox-sdk/referral-observations` with the same token: the value (prefix in lower case,\n  key in upper case), the UserId and the join time. Any other launch data is yours and is ignored.\n- **Retries.** At 0, 60, 180, 300, 600, 900, 1800 and 3600 seconds after the first attempt, so a short outage does not\n  lose an arrival. Every retry sends the same report, and R3FTO counts it once.\n- **Test and Production.** A Test token accepts only the Test keys `TSTA`, `TSTB` and `TSTC`; a Production token accepts\n  real creator keys. When R3FTO does not recognize a value, one warning is printed per server\n  (`a creator link value was not recognized`); later ones are info lines.\n- **Diagnostics.** `getDiagnostics().referralObservations` counts this server's arrivals, and\n  `getDiagnostics().referralOutcomes` counts R3FTO's answers (`recorded`, `already_recorded`, `unrecognized_reference`)\n  and `failed` (no answer after every attempt, or refused). No key and no UserId is printed or kept in diagnostics.\n\n## The R3FTO Key panel (optional)\n\nPlayers can also type a creator's R3FTO Key in your game. Call `R3FTO.openKeyPanel(player)` from server code, for\nexample when the player presses your own button. The panel's words and layout are fixed, and no function sets a key for\na player.\n\n- **What a key does.** A key the player types counts for that creator from the moment R3FTO records it, and comes before\n  any creator link. Between creator links, the last link still wins.\n- **What is sent.** `POST {apiBaseUrl}/v1/roblox-sdk/creator-selections` with your SDK token: the server-seen UserId and\n  the key. The panel shows only fixed words for each answer.\n- **Limits.** One request at a time per player and at most 60 a minute per server, so receipts keep their share of your\n  server's HTTP requests. R3FTO also limits requests per game. A request is never retried on its own.\n- **Test and Production.** Use the Test token in Studio. A Test token accepts only the Test keys `TSTA`, `TSTB` and\n  `TSTC`. A Production token in Studio records real keys that count in public numbers.\n- **Diagnostics.** `getDiagnostics().keyPanelOutcomes` counts the answers. No key and no UserId is printed or kept.\n\n## Server signal\n\nAfter `start`, each game server tells R3FTO that it runs the SDK, so your Roblox page can show your servers and any\nreceipts they could not save.\n\n- **When.** `started` once after `start`, `alive` every hour, and `closing` once when the server shuts down (from\n  `game:BindToClose`, waiting at most 5 seconds).\n- **What.** The environment, universe, place, server JobId (in Studio, an id made for the session), SDK version, the\n  signal kind, the send time and this server's receipt counts by durability (`memory_only`,\n  `stored_awaiting_delivery`, `not_durable`). No PlayerId and nothing about players.\n- **How.** `POST {apiBaseUrl}/v1/roblox-sdk/heartbeats` with the same token. A signal runs in its own thread, never\n  inside your receipt handler. A failed signal is not retried; the next one follows on schedule. If R3FTO refuses it\n  (for example a wrong token or environment), one warning is printed per server. If the SDK token secret is not\n  available on the server, nothing is sent and one warning per server says so (`server signals are not sent`); the\n  warning at start names the secret and gives Roblox's own message.\n- **Never affects purchases.** The signal never changes a receipt, a purchase decision or anything R3FTO records about\n  purchases. `getDiagnostics().heartbeat` shows the latest signal's kind, send time and result.\n\n## Limits you should know\n\n- **Your game server is the source.** Receipts and DataStore records come from your own game server. They are not\n  independent Roblox transaction records, so a correct and complete integration matters.\n- **Loss window.** If both the DataStore copy and the R3FTO delivery fail and the server stops, the receipt and its first\n  observation time are lost. Nothing reconstructs or estimates them. A missing record is not proof that no sale\n  happened.\n- **Earliest time across servers.** Roblox can run `ProcessReceipt` for one receipt on two servers at once. The DataStore\n  keeps the first record that committed. R3FTO keeps the first delivery that committed and counts any later report that\n  differs. During an outage, the time R3FTO keeps can be later than the true first observation on another server.\n- **No automatic deletion.** The SDK never deletes its DataStore records. Your existing data-deletion duties\n  (including Roblox Right to Erasure) still apply; records carry the buyer's UserId to support them.\n- **Throughput.** The SDK checks the server's DataStore budget before writing and sends at most one request per channel\n  attempt, well within Roblox's per-server HTTP and DataStore limits.\n\n## Wire contract (for reference)\n\nRoblox ids and Robux amounts are decimal strings. Times are ISO 8601 UTC with milliseconds.\n\n```json\nPOST /v1/roblox-sdk/receipts\n{ \"environment\": \"test\", \"universe_id\": \"123\", \"place_id\": \"456\", \"server_job_id\": \"…\", \"sdk_version\": \"0.4.0\",\n  \"simulated\": false,\n  \"receipt\": { \"purchase_id\": \"…\", \"player_id\": \"1\", \"product_id\": \"2\", \"currency_spent\": \"200\",\n               \"currency_type\": \"Robux\", \"place_id_where_purchased\": \"456\", \"purchase_channel\": null },\n  \"first_observed_at\": \"2026-11-11T10:30:45.123Z\", \"record_source\": \"sdk_direct\" }\n→ 200 { \"outcome\": \"recorded\" | \"already_recorded\", \"receipt_id\": \"…\", \"first_observed_at\": \"…\",\n        \"matches_first_record\": true }\n\nPOST /v1/roblox-sdk/referral-observations\n{ \"environment\", \"universe_id\", \"place_id\", \"server_job_id\", \"sdk_version\",\n  \"roblox_user_id\": \"1\", \"launch_reference\": \"r3f_KAEL\", \"observed_at\": \"…Z\" }\n→ 200 { \"outcome\": \"recorded\" | \"already_recorded\" | \"unrecognized_reference\" }\n\nPOST /v1/roblox-sdk/heartbeats\n{ \"environment\", \"universe_id\", \"place_id\", \"server_job_id\", \"sdk_version\",\n  \"kind\": \"started\" | \"alive\" | \"closing\", \"sent_at\": \"…Z\",\n  \"receipts\": { \"memory_only\": 0, \"stored_awaiting_delivery\": 0, \"not_durable\": 0 } }\n→ 200 { \"outcome\": \"recorded\" }\n\nPOST /v1/roblox-sdk/creator-selections\n{ \"environment\", \"universe_id\", \"place_id\", \"server_job_id\", \"sdk_version\",\n  \"roblox_user_id\": \"1\", \"action\": \"set\", \"creator_key\": \"KAEL\" }\n→ 200 { \"outcome\": \"accepted\" | \"unknown_key\" | \"unavailable\" }\n```\n\nErrors use the standard R3FTO error body. Codes:\n\n- `400 VALIDATION_ERROR`.\n- `401 AUTHENTICATION_REQUIRED` and `401 CREDENTIAL_REVOKED`.\n- `403 ENVIRONMENT_MISMATCH`, `403 UNIVERSE_MISMATCH` and `403 SIMULATION_NOT_ALLOWED`.\n- `413`, `415` and `503 SERVICE_UNAVAILABLE`.\n- `429 RATE_LIMITED`.\n\nDataStore value (schema 1):\n\n- `schema`, `purchaseId`, `playerId`, `productId`, `currencySpent`, `currencyType`, `placeIdWherePurchased`.\n- `purchaseChannel`, `universeId`, `environment`, `firstObservedAtUtc`, `firstObservedServerJobId`, `sdkVersion`,\n  `simulated`.\n\n## Tests\n\n- `luau tests/run.luau` runs the SDK's real modules over fake Roblox services with a virtual clock. It checks:\n  - retry offsets, a channel stopping after it succeeds, Retry-After and rejection;\n  - duplicate callbacks, the immutable and adopted first observation time;\n  - independent DataStore and transport failures, the no-I/O handler call;\n  - the pre-start queue, environment scopes, simulation marking and log hygiene;\n  - creator link values: the accepted format, one report per join, the arrival retry schedule and the warning;\n  - the server signal: its hourly schedule, no retry, the counts, the closing wait limit and the Studio id.\n- CI runs these tests on every push, builds `R3FTO.rbxm` with Rojo and checks that the example place builds.\n- To check your own integration end to end, use your R3FTO Test token in a published Test experience, then look at\n  Last SDK signal on your game's Roblox tab.\n","readmeTruncated":false}