@flare-engine/achievements 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grzegorz Otto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @flare-engine/achievements
+
+Typed `AchievementsProvider` interface + `NoopAchievementsProvider` + React context. Stub-only at 0.1.0; concrete adapters (Game Center, Google Play Games, Steam) land at 0.2.0.
+
+## Install
+
+```sh
+bun add @flare-engine/achievements
+```
+
+## Usage
+
+```tsx
+import {
+  AchievementsContext,
+  useAchievements,
+  NoopAchievementsProvider,
+} from '@flare-engine/achievements';
+
+export function App() {
+  return (
+    <AchievementsContext.Provider value={NoopAchievementsProvider}>
+      {/* ... */}
+    </AchievementsContext.Provider>
+  );
+}
+```
+
+`useAchievements()` returns the provider; call `unlock(id)`, `setProgress(id, n)`, etc. against the interface — swapping `NoopAchievementsProvider` for a real adapter at 0.2.0 requires no consumer changes.
+
+## Recipe — env-var-gated lazy load
+
+When 0.2.0 adapters land (e.g. `@flare-engine/achievements-gamecenter`), wrap them behind an env-var gate so CI / unit tests / dev builds without API keys fall back to `NoopAchievementsProvider` and never touch the native SDK. See [.github/skills/flare-tier2-stubs/SKILL.md § Lazy-SDK adapter recipe](../../.github/skills/flare-tier2-stubs/SKILL.md#lazy-sdk-adapter-recipe) for the full pattern; canonical implementation at [apps/pan-tvardowski/src/iap/provider.ts](../../apps/pan-tvardowski/src/iap/provider.ts) (RevenueCat / IAP — same shape).

package/dist/index.d.mts

@@ -0,0 +1,37 @@
+import * as react from 'react';
+
+/** Opaque achievement identifier — adapter-defined. */
+type AchievementId = string;
+/** Current state of an achievement for the local player. */
+interface AchievementState {
+    id: AchievementId;
+    unlocked: boolean;
+    /** Partial progress in the range [0, 1]. `1` implies `unlocked: true`. */
+    progress: number;
+    unlockedAt?: number;
+}
+/**
+ * Achievement provider interface. Consumers supply a concrete adapter (Game
+ * Center, Google Play Games, Steam, custom backend) at the app boundary.
+ * `unlock()` is idempotent by contract — adapters must dedupe.
+ */
+interface AchievementsProvider {
+    unlock(id: AchievementId, progress?: number): Promise<void>;
+    getState(id: AchievementId): Promise<AchievementState>;
+    getAll(): Promise<readonly AchievementState[]>;
+}
+/**
+ * Default no-op provider. All queries report `unlocked: false, progress: 0`;
+ * unlocks resolve silently.
+ */
+declare const NoopAchievementsProvider: AchievementsProvider;
+
+/**
+ * React context carrying the active `AchievementsProvider`. Defaults to
+ * `NoopAchievementsProvider`.
+ */
+declare const AchievementsContext: react.Context<AchievementsProvider>;
+/** Hook returning the current `AchievementsProvider`. */
+declare function useAchievements(): AchievementsProvider;
+
+export { type AchievementId, type AchievementState, AchievementsContext, type AchievementsProvider, NoopAchievementsProvider, useAchievements };

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import * as react from 'react';
+
+/** Opaque achievement identifier — adapter-defined. */
+type AchievementId = string;
+/** Current state of an achievement for the local player. */
+interface AchievementState {
+    id: AchievementId;
+    unlocked: boolean;
+    /** Partial progress in the range [0, 1]. `1` implies `unlocked: true`. */
+    progress: number;
+    unlockedAt?: number;
+}
+/**
+ * Achievement provider interface. Consumers supply a concrete adapter (Game
+ * Center, Google Play Games, Steam, custom backend) at the app boundary.
+ * `unlock()` is idempotent by contract — adapters must dedupe.
+ */
+interface AchievementsProvider {
+    unlock(id: AchievementId, progress?: number): Promise<void>;
+    getState(id: AchievementId): Promise<AchievementState>;
+    getAll(): Promise<readonly AchievementState[]>;
+}
+/**
+ * Default no-op provider. All queries report `unlocked: false, progress: 0`;
+ * unlocks resolve silently.
+ */
+declare const NoopAchievementsProvider: AchievementsProvider;
+
+/**
+ * React context carrying the active `AchievementsProvider`. Defaults to
+ * `NoopAchievementsProvider`.
+ */
+declare const AchievementsContext: react.Context<AchievementsProvider>;
+/** Hook returning the current `AchievementsProvider`. */
+declare function useAchievements(): AchievementsProvider;
+
+export { type AchievementId, type AchievementState, AchievementsContext, type AchievementsProvider, NoopAchievementsProvider, useAchievements };

package/dist/index.js

@@ -0,0 +1,53 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AchievementsContext: () => AchievementsContext,
+  NoopAchievementsProvider: () => NoopAchievementsProvider,
+  useAchievements: () => useAchievements
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/provider.ts
+var NoopAchievementsProvider = {
+  async unlock() {
+  },
+  async getState(id) {
+    return { id, unlocked: false, progress: 0 };
+  },
+  async getAll() {
+    return [];
+  }
+};
+
+// src/context.ts
+var import_react = require("react");
+var AchievementsContext = (0, import_react.createContext)(NoopAchievementsProvider);
+function useAchievements() {
+  return (0, import_react.useContext)(AchievementsContext);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AchievementsContext,
+  NoopAchievementsProvider,
+  useAchievements
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/provider.ts","../src/context.ts"],"sourcesContent":["export {\n  NoopAchievementsProvider,\n  type AchievementId,\n  type AchievementState,\n  type AchievementsProvider,\n} from './provider.js';\nexport { AchievementsContext, useAchievements } from './context.js';\n","/** Opaque achievement identifier — adapter-defined. */\nexport type AchievementId = string;\n\n/** Current state of an achievement for the local player. */\nexport interface AchievementState {\n  id: AchievementId;\n  unlocked: boolean;\n  /** Partial progress in the range [0, 1]. `1` implies `unlocked: true`. */\n  progress: number;\n  unlockedAt?: number;\n}\n\n/**\n * Achievement provider interface. Consumers supply a concrete adapter (Game\n * Center, Google Play Games, Steam, custom backend) at the app boundary.\n * `unlock()` is idempotent by contract — adapters must dedupe.\n */\nexport interface AchievementsProvider {\n  unlock(id: AchievementId, progress?: number): Promise<void>;\n  getState(id: AchievementId): Promise<AchievementState>;\n  getAll(): Promise<readonly AchievementState[]>;\n}\n\n/**\n * Default no-op provider. All queries report `unlocked: false, progress: 0`;\n * unlocks resolve silently.\n */\nexport const NoopAchievementsProvider: AchievementsProvider = {\n  async unlock(): Promise<void> {\n    // no-op\n  },\n  async getState(id: AchievementId): Promise<AchievementState> {\n    return { id, unlocked: false, progress: 0 };\n  },\n  async getAll(): Promise<readonly AchievementState[]> {\n    return [];\n  },\n};\n","import { createContext, useContext } from 'react';\nimport { type AchievementsProvider, NoopAchievementsProvider } from './provider.js';\n\n/**\n * React context carrying the active `AchievementsProvider`. Defaults to\n * `NoopAchievementsProvider`.\n */\nexport const AchievementsContext = createContext<AchievementsProvider>(NoopAchievementsProvider);\n\n/** Hook returning the current `AchievementsProvider`. */\nexport function useAchievements(): AchievementsProvider {\n  return useContext(AchievementsContext);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC2BO,IAAM,2BAAiD;AAAA,EAC5D,MAAM,SAAwB;AAAA,EAE9B;AAAA,EACA,MAAM,SAAS,IAA8C;AAC3D,WAAO,EAAE,IAAI,UAAU,OAAO,UAAU,EAAE;AAAA,EAC5C;AAAA,EACA,MAAM,SAA+C;AACnD,WAAO,CAAC;AAAA,EACV;AACF;;;ACrCA,mBAA0C;AAOnC,IAAM,0BAAsB,4BAAoC,wBAAwB;AAGxF,SAAS,kBAAwC;AACtD,aAAO,yBAAW,mBAAmB;AACvC;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,24 @@
+// src/provider.ts
+var NoopAchievementsProvider = {
+  async unlock() {
+  },
+  async getState(id) {
+    return { id, unlocked: false, progress: 0 };
+  },
+  async getAll() {
+    return [];
+  }
+};
+
+// src/context.ts
+import { createContext, useContext } from "react";
+var AchievementsContext = createContext(NoopAchievementsProvider);
+function useAchievements() {
+  return useContext(AchievementsContext);
+}
+export {
+  AchievementsContext,
+  NoopAchievementsProvider,
+  useAchievements
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/provider.ts","../src/context.ts"],"sourcesContent":["/** Opaque achievement identifier — adapter-defined. */\nexport type AchievementId = string;\n\n/** Current state of an achievement for the local player. */\nexport interface AchievementState {\n  id: AchievementId;\n  unlocked: boolean;\n  /** Partial progress in the range [0, 1]. `1` implies `unlocked: true`. */\n  progress: number;\n  unlockedAt?: number;\n}\n\n/**\n * Achievement provider interface. Consumers supply a concrete adapter (Game\n * Center, Google Play Games, Steam, custom backend) at the app boundary.\n * `unlock()` is idempotent by contract — adapters must dedupe.\n */\nexport interface AchievementsProvider {\n  unlock(id: AchievementId, progress?: number): Promise<void>;\n  getState(id: AchievementId): Promise<AchievementState>;\n  getAll(): Promise<readonly AchievementState[]>;\n}\n\n/**\n * Default no-op provider. All queries report `unlocked: false, progress: 0`;\n * unlocks resolve silently.\n */\nexport const NoopAchievementsProvider: AchievementsProvider = {\n  async unlock(): Promise<void> {\n    // no-op\n  },\n  async getState(id: AchievementId): Promise<AchievementState> {\n    return { id, unlocked: false, progress: 0 };\n  },\n  async getAll(): Promise<readonly AchievementState[]> {\n    return [];\n  },\n};\n","import { createContext, useContext } from 'react';\nimport { type AchievementsProvider, NoopAchievementsProvider } from './provider.js';\n\n/**\n * React context carrying the active `AchievementsProvider`. Defaults to\n * `NoopAchievementsProvider`.\n */\nexport const AchievementsContext = createContext<AchievementsProvider>(NoopAchievementsProvider);\n\n/** Hook returning the current `AchievementsProvider`. */\nexport function useAchievements(): AchievementsProvider {\n  return useContext(AchievementsContext);\n}\n"],"mappings":";AA2BO,IAAM,2BAAiD;AAAA,EAC5D,MAAM,SAAwB;AAAA,EAE9B;AAAA,EACA,MAAM,SAAS,IAA8C;AAC3D,WAAO,EAAE,IAAI,UAAU,OAAO,UAAU,EAAE;AAAA,EAC5C;AAAA,EACA,MAAM,SAA+C;AACnD,WAAO,CAAC;AAAA,EACV;AACF;;;ACrCA,SAAS,eAAe,kBAAkB;AAOnC,IAAM,sBAAsB,cAAoC,wBAAwB;AAGxF,SAAS,kBAAwC;AACtD,SAAO,WAAW,mBAAmB;AACvC;","names":[]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@flare-engine/achievements",
+  "version": "0.1.0",
+  "description": "Achievements provider interface (consumer-supplied adapter)",
+  "keywords": ["flare-engine", "achievements", "provider", "interface"],
+  "license": "MIT",
+  "author": "Grzegorz Otto",
+  "homepage": "https://github.com/grzott/flare-engine#readme",
+  "bugs": {
+    "url": "https://github.com/grzott/flare-engine/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/grzott/flare-engine.git",
+    "directory": "packages/achievements"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsup",
+    "test": "bun test",
+    "lint": "biome check src/",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false
+}