@cricnice/online-contracts 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,14 @@
-# Temporary Holding Version
+# CricNice Online Contracts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Online-only API and event contracts shared by the mobile app and backend. Offline/Realm scoring types stay in their existing packages.
+
+## Scoring API
+
+`src/scoring/scoreCommand.ts` is the canonical contract for:
+
+- `ScoreCommand` and its `DELIVERY`, `EVENT`, and `CORRECTION` variants
+- `DeliveryPayload` and `MatchEventPayload`
+- Per-event `MatchScoringState` snapshots and command responses
+- Stable scoring error codes and runtime command validation
+
+Build with `npm run build`. Consumers should depend on this package by a pinned version once it is published or otherwise made available to both repositories. The package contains no mobile UI, Supabase client, Realm model, or backend implementation.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './scoring/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export * from './scoring/index.js';

package/dist/scoring/index.d.ts

@@ -0,0 +1,2 @@
+export * from './scoreCommand.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/scoring/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scoring/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/dist/scoring/index.js

@@ -0,0 +1 @@
+export * from './scoreCommand.js';

package/dist/scoring/scoreCommand.d.ts

@@ -0,0 +1,215 @@
+/** Stable public contract for commands submitted to the online scoring API. */
+export declare const SCORE_CONTRACT_VERSION: 1;
+export type UUID = string;
+export type MatchState = 'UPCOMING' | 'LIVE' | 'COMPLETED' | 'ABANDONED';
+export type MatchResult = 'PENDING' | 'WON' | 'TIE' | 'NO_RESULT';
+export type ScoreCommandBase = {
+    schemaVersion: typeof SCORE_CONTRACT_VERSION;
+    /** Idempotency key. Reuse this ID when retrying the same command. */
+    eventId: UUID;
+    matchId: UUID;
+    inningsId: UUID;
+    /** Current match-wide revision observed by the scorer. */
+    expectedRevision: number;
+};
+export type DeliveryType = 'NORMAL' | 'WD' | 'NB';
+export type ExtraRunType = 'BYE' | 'LB';
+/** Dismissals recorded as part of a delivery. Non-delivery dismissals are events. */
+export type DeliveryWicketType = 'BOWLED' | 'CAUGHT' | 'RUN_OUT' | 'STUMPED' | 'LBW' | 'HIT_WICKET' | 'OBSTRUCTING_FIELD' | 'OVER_THE_FENCE';
+export type RunOutDetails = {
+    type: 'DIRECT';
+    directFielderId: UUID;
+    assistFielderId?: never;
+} | {
+    type: 'ASSISTED';
+    directFielderId: UUID;
+    assistFielderId: UUID;
+};
+export type DeliveryPayload = {
+    ballType: DeliveryType;
+    /** Batter runs. Must be zero for wides and BYE/LB deliveries. */
+    runs: number;
+    /** Extra runs in addition to automatic wide/no-ball penalty. */
+    extraRuns: number;
+    extraRunType: ExtraRunType | null;
+    wicketType: DeliveryWicketType | null;
+    strikerId: UUID;
+    nonStrikerId: UUID | null;
+    bowlerId: UUID;
+    outBatterId: UUID | null;
+    fielderId: UUID | null;
+    runOut: RunOutDetails | null;
+};
+export type SetOpenersEvent = {
+    eventType: 'SET_OPENERS';
+    eventMeta: {
+        strikerId: UUID;
+        nonStrikerId: UUID | null;
+        bowlerId: UUID;
+    };
+};
+export type NewBatterEvent = {
+    eventType: 'NEW_BATTER';
+    eventMeta: {
+        batterId: UUID;
+        battingPosition?: number;
+    };
+};
+export type NewBowlerEvent = {
+    eventType: 'NEW_BOWLER';
+    eventMeta: {
+        bowlerId: UUID;
+    };
+};
+export type RetiredHurtEvent = {
+    eventType: 'RETIRED_HURT';
+    eventMeta: {
+        batterId: UUID;
+        reason?: string;
+    };
+};
+export type RetiredOutEvent = {
+    eventType: 'RETIRED_OUT';
+    eventMeta: {
+        batterId: UUID;
+        reason?: string;
+    };
+};
+export type TimedOutEvent = {
+    eventType: 'TIMED_OUT';
+    eventMeta: {
+        batterId: UUID;
+    };
+};
+export type MankadEvent = {
+    eventType: 'MANKAD';
+    eventMeta: {
+        batterId: UUID;
+        bowlerId: UUID;
+    };
+};
+export type InningsEndEvent = {
+    eventType: 'INNINGS_END';
+    eventMeta: {
+        reason?: 'DECLARED' | 'TARGET_REACHED' | 'ABANDONED' | 'OTHER';
+    };
+};
+export type StartSuperOverEvent = {
+    eventType: 'START_SUPER_OVER';
+    eventMeta: {
+        reason?: 'TIE' | 'OTHER';
+    };
+};
+export type MatchEventPayload = SetOpenersEvent | NewBatterEvent | NewBowlerEvent | RetiredHurtEvent | RetiredOutEvent | TimedOutEvent | MankadEvent | InningsEndEvent | StartSuperOverEvent;
+export type ScoreCommand = (ScoreCommandBase & {
+    kind: 'DELIVERY';
+    payload: DeliveryPayload;
+}) | (ScoreCommandBase & {
+    kind: 'EVENT';
+    payload: MatchEventPayload;
+}) | (ScoreCommandBase & {
+    kind: 'CORRECTION';
+    payload: {
+        targetEventId: UUID;
+    };
+});
+export type ExtraSummary = {
+    wides: number;
+    noBalls: number;
+    byes: number;
+    legByes: number;
+    penalty: number;
+    total: number;
+};
+export type BatterScoreState = {
+    playerId: UUID;
+    runs: number;
+    balls: number;
+    fours: number;
+    sixes: number;
+    isOut: boolean;
+};
+export type BowlerScoreState = {
+    playerId: UUID;
+    runsConceded: number;
+    legalBalls: number;
+    wickets: number;
+};
+/** Compact authoritative state immediately after one event was applied. */
+export type MatchScoringState = {
+    schemaVersion: typeof SCORE_CONTRACT_VERSION;
+    matchId: UUID;
+    matchRevision: number;
+    matchState: MatchState;
+    matchResult: MatchResult;
+    activeInningsId: UUID | null;
+    innings: {
+        inningsId: UUID;
+        inningsNumber: number;
+        superOverNumber: number;
+        battingTeamId: UUID;
+        runs: number;
+        wickets: number;
+        legalBalls: number;
+        ballsPerOver: number;
+        extras: ExtraSummary;
+        isCompleted: boolean;
+        strikerId: UUID | null;
+        nonStrikerId: UUID | null;
+        bowlerId: UUID | null;
+        batters: Record<UUID, BatterScoreState>;
+        bowlers: Record<UUID, BowlerScoreState>;
+    };
+    teamScores: Array<{
+        teamId: UUID;
+        inningsNumber: number;
+        superOverNumber: number;
+        runs: number;
+        wickets: number;
+        legalBalls: number;
+    }>;
+};
+type ScoringEventRecordBase = {
+    eventId: UUID;
+    matchId: UUID;
+    inningsId: UUID;
+    revision: number;
+    sequenceNumber: number;
+    reversesEventId: UUID | null;
+    actorUserId: UUID;
+    createdAt: string;
+    /** Persisted immutable state immediately after this event. */
+    stateAfter: MatchScoringState;
+};
+export type ScoringEventRecord = (ScoringEventRecordBase & {
+    kind: 'DELIVERY';
+    payload: DeliveryPayload;
+}) | (ScoringEventRecordBase & {
+    kind: 'EVENT';
+    payload: MatchEventPayload;
+}) | (ScoringEventRecordBase & {
+    kind: 'CORRECTION';
+    payload: {
+        targetEventId: UUID;
+    };
+});
+export type ScoreCommandResult = {
+    event: ScoringEventRecord;
+    /** Current match head; may be newer than event.revision on an idempotent retry. */
+    currentRevision: number;
+    duplicate: boolean;
+};
+export type ScoreCommandErrorCode = 'AUTHENTICATION_REQUIRED' | 'PROFILE_INCOMPLETE' | 'SCORER_REQUIRED' | 'MATCH_UNAVAILABLE' | 'INNINGS_UNAVAILABLE' | 'REVISION_CONFLICT' | 'INVALID_COMMAND' | 'PLAYER_NOT_IN_SQUAD' | 'INNINGS_COMPLETE' | 'EVENT_ID_REUSED' | 'UNDO_NOT_LATEST' | 'INTERNAL_ERROR';
+export type ScoreCommandError = {
+    error: {
+        code: ScoreCommandErrorCode;
+        message: string;
+        currentRevision?: number;
+    };
+};
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isUUID(value: unknown): value is UUID;
+/** Runtime guard for the shared HTTP command envelope and its discriminated payload. */
+export declare function isScoreCommand(value: unknown): value is ScoreCommand;
+export {};
+//# sourceMappingURL=scoreCommand.d.ts.map

package/dist/scoring/scoreCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoreCommand.d.ts","sourceRoot":"","sources":["../../src/scoring/scoreCommand.ts"],"names":[],"mappings":"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"}

package/dist/scoring/scoreCommand.js

@@ -0,0 +1,97 @@
+/** Stable public contract for commands submitted to the online scoring API. */
+export const SCORE_CONTRACT_VERSION = 1;
+export function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export function isUUID(value) {
+    return typeof value === 'string' && UUID_PATTERN.test(value);
+}
+function isNonNegativeInteger(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+function isDeliveryPayload(value) {
+    if (!['NORMAL', 'WD', 'NB'].includes(String(value.ballType)))
+        return false;
+    if (!isNonNegativeInteger(value.runs) || !isNonNegativeInteger(value.extraRuns))
+        return false;
+    if (value.extraRunType !== null && value.extraRunType !== 'BYE' && value.extraRunType !== 'LB')
+        return false;
+    const wicketTypes = [
+        'BOWLED', 'CAUGHT', 'RUN_OUT', 'STUMPED', 'LBW', 'HIT_WICKET',
+        'OBSTRUCTING_FIELD', 'OVER_THE_FENCE',
+    ];
+    if (value.wicketType !== null && !wicketTypes.includes(value.wicketType))
+        return false;
+    if (!isUUID(value.strikerId) || !isUUID(value.bowlerId))
+        return false;
+    if (value.nonStrikerId !== null && !isUUID(value.nonStrikerId))
+        return false;
+    if (value.outBatterId !== null && !isUUID(value.outBatterId))
+        return false;
+    if (value.fielderId !== null && !isUUID(value.fielderId))
+        return false;
+    if ((value.wicketType === null) !== (value.outBatterId === null))
+        return false;
+    if (value.ballType === 'WD' && value.runs !== 0)
+        return false;
+    if ((value.extraRunType === 'BYE' || value.extraRunType === 'LB') && value.runs !== 0)
+        return false;
+    if (value.wicketType === 'CAUGHT' && !isUUID(value.fielderId))
+        return false;
+    if (value.wicketType === 'RUN_OUT') {
+        if (!isRecord(value.runOut))
+            return false;
+        if (value.runOut.type === 'DIRECT') {
+            if (!isUUID(value.runOut.directFielderId) || value.runOut.assistFielderId != null)
+                return false;
+        }
+        else if (value.runOut.type === 'ASSISTED') {
+            if (!isUUID(value.runOut.directFielderId) || !isUUID(value.runOut.assistFielderId))
+                return false;
+        }
+        else
+            return false;
+    }
+    else if (value.runOut !== null)
+        return false;
+    return value.runOut === null || value.wicketType === 'RUN_OUT';
+}
+function isMatchEventPayload(value) {
+    if (!isRecord(value.eventMeta) || typeof value.eventType !== 'string')
+        return false;
+    const meta = value.eventMeta;
+    switch (value.eventType) {
+        case 'SET_OPENERS':
+            return isUUID(meta.strikerId) && isUUID(meta.bowlerId) &&
+                (meta.nonStrikerId === null || isUUID(meta.nonStrikerId));
+        case 'NEW_BATTER':
+            return isUUID(meta.batterId) &&
+                (meta.battingPosition === undefined || (Number.isSafeInteger(meta.battingPosition) && Number(meta.battingPosition) > 0));
+        case 'NEW_BOWLER': return isUUID(meta.bowlerId);
+        case 'RETIRED_HURT':
+        case 'RETIRED_OUT': return isUUID(meta.batterId) && (meta.reason === undefined || typeof meta.reason === 'string');
+        case 'TIMED_OUT': return isUUID(meta.batterId);
+        case 'MANKAD': return isUUID(meta.batterId) && isUUID(meta.bowlerId);
+        case 'INNINGS_END':
+            return meta.reason === undefined || ['DECLARED', 'TARGET_REACHED', 'ABANDONED', 'OTHER'].includes(String(meta.reason));
+        case 'START_SUPER_OVER':
+            return meta.reason === undefined || ['TIE', 'OTHER'].includes(String(meta.reason));
+        default: return false;
+    }
+}
+/** Runtime guard for the shared HTTP command envelope and its discriminated payload. */
+export function isScoreCommand(value) {
+    if (!isRecord(value) || value.schemaVersion !== SCORE_CONTRACT_VERSION)
+        return false;
+    if (!isUUID(value.eventId) || !isUUID(value.matchId) || !isUUID(value.inningsId))
+        return false;
+    if (!isNonNegativeInteger(value.expectedRevision) || !isRecord(value.payload))
+        return false;
+    switch (value.kind) {
+        case 'DELIVERY': return isDeliveryPayload(value.payload);
+        case 'EVENT': return isMatchEventPayload(value.payload);
+        case 'CORRECTION': return isUUID(value.payload.targetEventId);
+        default: return false;
+    }
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@cricnice/online-contracts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Shared online scoring API contracts for CricNice mobile and backend",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}