checkinkit 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,213 @@
1
- # Temporary Holding Version
1
+ # CheckInKit
2
2
 
3
- 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.
3
+ **A lightweight JavaScript event ticket validation and attendee check-in toolkit.**
4
+
5
+ CheckInKit helps event organizers register attendees, generate unique ticket IDs, validate tickets, manage check-ins and check-outs, and track attendance statistics.
6
+
7
+ Designed for hackathons, college fests, conferences, workshops, and other events.
8
+
9
+ ## Features
10
+
11
+ - Register attendees with name and email
12
+ - Generate unique ticket IDs
13
+ - Validate ticket status
14
+ - Check attendees in and out
15
+ - Prevent duplicate registration using email
16
+ - Prevent duplicate check-ins
17
+ - Set an optional event capacity
18
+ - View event attendance statistics
19
+ - Export registered ticket data
20
+ - Built with Node.js — no external dependencies
21
+
22
+ ## Installation
23
+
24
+ Install CheckInKit from npm:
25
+
26
+ ```bash
27
+ npm install checkinkit
28
+ ```
29
+
30
+ ## Quick Start
31
+
32
+ ```javascript
33
+ const CheckInKit = require("checkinkit");
34
+
35
+ const event = new CheckInKit({
36
+ eventName: "Tech Fest 2026",
37
+ capacity: 100
38
+ });
39
+
40
+ // Register an attendee
41
+ const attendee = event.registerAttendee({
42
+ name: "Chirag Antil",
43
+ email: "chirag@example.com"
44
+ });
45
+
46
+ console.log("Ticket ID:", attendee.ticketId);
47
+
48
+ // Validate the ticket
49
+ const validation = event.validateTicket(attendee.ticketId);
50
+ console.log(validation);
51
+
52
+ // Check the attendee in
53
+ const checkIn = event.checkIn(attendee.ticketId);
54
+ console.log(checkIn);
55
+
56
+ // Get attendance statistics
57
+ console.log(event.getStats());
58
+ ```
59
+
60
+ ## API Reference
61
+
62
+ ### `new CheckInKit(options)`
63
+
64
+ Creates a new event check-in manager.
65
+
66
+ | Option | Type | Description |
67
+ | --- | --- | --- |
68
+ | `eventName` | `string` | Event name. Defaults to `"Untitled Event"` |
69
+ | `capacity` | `number` | Optional maximum number of attendees |
70
+
71
+ ```javascript
72
+ const event = new CheckInKit({
73
+ eventName: "Paranox 2.0",
74
+ capacity: 500
75
+ });
76
+ ```
77
+
78
+ Capacity must be a positive integer when provided.
79
+
80
+ ### `registerAttendee({ name, email })`
81
+
82
+ Registers a new attendee and generates a unique ticket ID.
83
+
84
+ ```javascript
85
+ const ticket = event.registerAttendee({
86
+ name: "Aarav Sharma",
87
+ email: "aarav@example.com"
88
+ });
89
+ ```
90
+
91
+ Returns the attendee ticket object.
92
+
93
+ Throws an error if the name or email is invalid, the email is already registered, or the event has reached its capacity.
94
+
95
+ ### `validateTicket(ticketId)`
96
+
97
+ Checks whether a ticket exists and can be used for check-in.
98
+
99
+ ```javascript
100
+ const result = event.validateTicket(ticket.ticketId);
101
+
102
+ if (result.valid) {
103
+ console.log("Ticket is valid");
104
+ }
105
+ ```
106
+
107
+ Returns an object containing `valid`, `message`, and the ticket when valid.
108
+
109
+ ### `checkIn(ticketId)`
110
+
111
+ Checks in an attendee with a valid, unused ticket.
112
+
113
+ ```javascript
114
+ const result = event.checkIn(ticket.ticketId);
115
+ console.log(result.message);
116
+ ```
117
+
118
+ Returns `success`, `message`, and the updated ticket on success.
119
+
120
+ A ticket can only be checked in once.
121
+
122
+ ### `checkOut(ticketId)`
123
+
124
+ Checks out an attendee who has already checked in.
125
+
126
+ ```javascript
127
+ const result = event.checkOut(ticket.ticketId);
128
+ console.log(result.message);
129
+ ```
130
+
131
+ Returns `success`, `message`, and the updated ticket on success.
132
+
133
+ ### `getTicket(ticketId)`
134
+
135
+ Returns the ticket details for a ticket ID, or `null` if it does not exist.
136
+
137
+ ```javascript
138
+ const ticketDetails = event.getTicket(ticket.ticketId);
139
+ ```
140
+
141
+ ### `getStats()`
142
+
143
+ Returns event attendance statistics.
144
+
145
+ ```javascript
146
+ console.log(event.getStats());
147
+ ```
148
+
149
+ Example response:
150
+
151
+ ```javascript
152
+ {
153
+ eventName: "Tech Fest 2026",
154
+ capacity: 100,
155
+ total: 1,
156
+ checkedIn: 1,
157
+ checkedOut: 0,
158
+ notCheckedIn: 0,
159
+ availableSeats: 99
160
+ }
161
+ ```
162
+
163
+ ### `exportTickets()`
164
+
165
+ Returns an array containing all registered ticket records.
166
+
167
+ ```javascript
168
+ const tickets = event.exportTickets();
169
+ console.log(tickets);
170
+ ```
171
+
172
+ ## Ticket Status
173
+
174
+ Tickets can have the following statuses:
175
+
176
+ - `registered` — attendee has registered but not checked in
177
+ - `checked-in` — attendee has checked in
178
+ - `checked-out` — attendee has checked out
179
+
180
+ ## Example
181
+
182
+ Run the included example:
183
+
184
+ ```bash
185
+ node examples/basic.js
186
+ ```
187
+
188
+ ## Run Tests
189
+
190
+ CheckInKit uses Node.js's built-in test runner.
191
+
192
+ ```bash
193
+ npm test
194
+ ```
195
+
196
+ ## Important Notes
197
+
198
+ - CheckInKit stores ticket data in memory. Data is not automatically saved to a database or file.
199
+ - The event organizer's application is responsible for persistent storage.
200
+ - Ticket IDs are generated using Node.js's `crypto.randomUUID()`.
201
+ - This package is designed as a lightweight check-in utility and does not include a frontend, QR-code scanner, or database integration.
202
+
203
+ ## Use Cases
204
+
205
+ - College fests and hackathons
206
+ - Conferences and workshops
207
+ - Student community events
208
+ - Meetup registrations
209
+ - Event entry and attendance tracking
210
+
211
+ ## License
212
+
213
+ MIT
@@ -0,0 +1,19 @@
1
+ const CheckInKit = require("../");
2
+
3
+ const event = new CheckInKit({
4
+ eventName: "Paranox 2.0"
5
+ });
6
+
7
+ const ticket = event.registerAttendee({
8
+ name: "Chirag Antil",
9
+ email: "chirag@example.com"
10
+ });
11
+
12
+ console.log("Ticket generated:");
13
+ console.log(ticket);
14
+
15
+ console.log("\nChecking in attendee...");
16
+ console.log(event.checkIn(ticket.ticketId));
17
+
18
+ console.log("\nEvent attendance:");
19
+ console.log(event.getStats());
package/index.js ADDED
@@ -0,0 +1,3 @@
1
+ const CheckInKit = require("./src/checkinkit");
2
+
3
+ module.exports = CheckInKit;
package/package.json CHANGED
@@ -1,6 +1,25 @@
1
+
1
2
  {
2
3
  "name": "checkinkit",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
4
+ "version": "1.0.0",
5
+ "description": "Lightweight event ticket validation and check-in toolkit for JavaScript",
6
+ "main": "index.js",
7
+ "scripts": {
8
+ "test": "node --test"
9
+ },
10
+ "keywords": [
11
+ "event",
12
+ "check-in",
13
+ "ticket",
14
+ "attendance",
15
+ "hackathon",
16
+ "event-management",
17
+ "ticket-validation"
18
+ ],
19
+ "author": "Chirag Antil",
20
+ "license": "MIT",
21
+ "type": "commonjs",
22
+ "engines": {
23
+ "node": ">=18"
24
+ }
25
+ }
@@ -0,0 +1,172 @@
1
+ const { randomUUID } = require("node:crypto");
2
+
3
+ class CheckInKit {
4
+ constructor(options = {}) {
5
+ this.eventName = options.eventName || "Untitled Event";
6
+ this.capacity = options.capacity ?? Infinity;
7
+
8
+ if (
9
+ this.capacity !== Infinity &&
10
+ (!Number.isInteger(this.capacity) || this.capacity < 1)
11
+ ) {
12
+ throw new Error("Capacity must be a positive integer");
13
+ }
14
+
15
+ this.tickets = new Map();
16
+ }
17
+
18
+ registerAttendee({ name, email } = {}) {
19
+ if (!name || typeof name !== "string" || !name.trim()) {
20
+ throw new Error("Attendee name is required");
21
+ }
22
+
23
+ if (
24
+ !email ||
25
+ typeof email !== "string" ||
26
+ !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email.trim())
27
+ ) {
28
+ throw new Error("A valid email is required");
29
+ }
30
+
31
+ const normalizedEmail = email.trim().toLowerCase();
32
+
33
+ for (const ticket of this.tickets.values()) {
34
+ if (ticket.email === normalizedEmail) {
35
+ throw new Error("This attendee is already registered");
36
+ }
37
+ }
38
+
39
+ if (this.tickets.size >= this.capacity) {
40
+ throw new Error("Event is full");
41
+ }
42
+
43
+ const ticketId = `CK-${randomUUID()}`;
44
+
45
+ const ticket = {
46
+ ticketId,
47
+ name: name.trim(),
48
+ email: normalizedEmail,
49
+ status: "registered",
50
+ checkedInAt: null,
51
+ checkedOutAt: null
52
+ };
53
+
54
+ this.tickets.set(ticketId, ticket);
55
+
56
+ return { ...ticket };
57
+ }
58
+
59
+ validateTicket(ticketId) {
60
+ const ticket = this.tickets.get(ticketId);
61
+
62
+ if (!ticket) {
63
+ return {
64
+ valid: false,
65
+ message: "Ticket not found"
66
+ };
67
+ }
68
+
69
+ if (ticket.status !== "registered") {
70
+ return {
71
+ valid: false,
72
+ message: "Ticket already used"
73
+ };
74
+ }
75
+
76
+ return {
77
+ valid: true,
78
+ message: "Ticket is valid",
79
+ ticket: { ...ticket }
80
+ };
81
+ }
82
+
83
+ checkIn(ticketId) {
84
+ const result = this.validateTicket(ticketId);
85
+
86
+ if (!result.valid) {
87
+ return {
88
+ success: false,
89
+ message: result.message
90
+ };
91
+ }
92
+
93
+ const ticket = this.tickets.get(ticketId);
94
+
95
+ ticket.status = "checked-in";
96
+ ticket.checkedInAt = new Date().toISOString();
97
+
98
+ return {
99
+ success: true,
100
+ message: "Check-in successful",
101
+ ticket: { ...ticket }
102
+ };
103
+ }
104
+
105
+ checkOut(ticketId) {
106
+ const ticket = this.tickets.get(ticketId);
107
+
108
+ if (!ticket) {
109
+ return {
110
+ success: false,
111
+ message: "Ticket not found"
112
+ };
113
+ }
114
+
115
+ if (ticket.status !== "checked-in") {
116
+ return {
117
+ success: false,
118
+ message: "Attendee must check in before checking out"
119
+ };
120
+ }
121
+
122
+ ticket.status = "checked-out";
123
+ ticket.checkedOutAt = new Date().toISOString();
124
+
125
+ return {
126
+ success: true,
127
+ message: "Check-out successful",
128
+ ticket: { ...ticket }
129
+ };
130
+ }
131
+
132
+ getTicket(ticketId) {
133
+ const ticket = this.tickets.get(ticketId);
134
+
135
+ return ticket ? { ...ticket } : null;
136
+ }
137
+
138
+ getStats() {
139
+ const total = this.tickets.size;
140
+ let checkedIn = 0;
141
+ let checkedOut = 0;
142
+
143
+ for (const ticket of this.tickets.values()) {
144
+ if (ticket.status === "checked-in") {
145
+ checkedIn++;
146
+ }
147
+
148
+ if (ticket.status === "checked-out") {
149
+ checkedOut++;
150
+ }
151
+ }
152
+
153
+ return {
154
+ eventName: this.eventName,
155
+ capacity: this.capacity === Infinity ? null : this.capacity,
156
+ total,
157
+ checkedIn,
158
+ checkedOut,
159
+ notCheckedIn: total - checkedIn - checkedOut,
160
+ availableSeats:
161
+ this.capacity === Infinity ? null : this.capacity - total
162
+ };
163
+ }
164
+
165
+ exportTickets() {
166
+ return Array.from(this.tickets.values()).map(ticket => ({
167
+ ...ticket
168
+ }));
169
+ }
170
+ }
171
+
172
+ module.exports = CheckInKit;
@@ -0,0 +1,148 @@
1
+ const test = require("node:test");
2
+ const assert = require("node:assert/strict");
3
+ const CheckInKit = require("../");
4
+
5
+ test("registers a new attendee", () => {
6
+ const kit = new CheckInKit({ eventName: "Hackathon" });
7
+
8
+ const ticket = kit.registerAttendee({
9
+ name: "Chirag",
10
+ email: "chirag@example.com"
11
+ });
12
+
13
+ assert.ok(ticket.ticketId);
14
+ assert.equal(ticket.status, "registered");
15
+ assert.equal(ticket.name, "Chirag");
16
+ });
17
+
18
+ test("rejects duplicate registrations", () => {
19
+ const kit = new CheckInKit();
20
+
21
+ kit.registerAttendee({
22
+ name: "Chirag",
23
+ email: "chirag@example.com"
24
+ });
25
+
26
+ assert.throws(() => {
27
+ kit.registerAttendee({
28
+ name: "Another User",
29
+ email: "CHIRAG@example.com"
30
+ });
31
+ }, /already registered/);
32
+ });
33
+
34
+ test("successfully checks in a valid ticket", () => {
35
+ const kit = new CheckInKit();
36
+
37
+ const ticket = kit.registerAttendee({
38
+ name: "Chirag",
39
+ email: "chirag@example.com"
40
+ });
41
+
42
+ const result = kit.checkIn(ticket.ticketId);
43
+
44
+ assert.equal(result.success, true);
45
+ assert.equal(result.ticket.status, "checked-in");
46
+ assert.ok(result.ticket.checkedInAt);
47
+ });
48
+
49
+ test("rejects duplicate check-in", () => {
50
+ const kit = new CheckInKit();
51
+
52
+ const ticket = kit.registerAttendee({
53
+ name: "Chirag",
54
+ email: "chirag@example.com"
55
+ });
56
+
57
+ kit.checkIn(ticket.ticketId);
58
+
59
+ const result = kit.checkIn(ticket.ticketId);
60
+
61
+ assert.equal(result.success, false);
62
+ assert.match(result.message, /already used/);
63
+ });
64
+
65
+ test("rejects an unknown ticket", () => {
66
+ const kit = new CheckInKit();
67
+
68
+ const result = kit.checkIn("INVALID-TICKET");
69
+
70
+ assert.equal(result.success, false);
71
+ assert.equal(result.message, "Ticket not found");
72
+ });
73
+
74
+ test("calculates attendance statistics", () => {
75
+ const kit = new CheckInKit({
76
+ eventName: "Tech Fest",
77
+ capacity: 10
78
+ });
79
+
80
+ const first = kit.registerAttendee({
81
+ name: "Chirag",
82
+ email: "chirag@example.com"
83
+ });
84
+
85
+ kit.registerAttendee({
86
+ name: "Aryan",
87
+ email: "aryan@example.com"
88
+ });
89
+
90
+ kit.checkIn(first.ticketId);
91
+
92
+ const stats = kit.getStats();
93
+
94
+ assert.equal(stats.eventName, "Tech Fest");
95
+ assert.equal(stats.capacity, 10);
96
+ assert.equal(stats.total, 2);
97
+ assert.equal(stats.checkedIn, 1);
98
+ assert.equal(stats.checkedOut, 0);
99
+ assert.equal(stats.notCheckedIn, 1);
100
+ assert.equal(stats.availableSeats, 8);
101
+ });
102
+
103
+ test("rejects invalid email", () => {
104
+ const kit = new CheckInKit();
105
+
106
+ assert.throws(() => {
107
+ kit.registerAttendee({
108
+ name: "Chirag",
109
+ email: "invalid-email"
110
+ });
111
+ }, /valid email/);
112
+ });
113
+
114
+ test("checks out an attendee after check-in", () => {
115
+ const kit = new CheckInKit();
116
+
117
+ const ticket = kit.registerAttendee({
118
+ name: "Chirag",
119
+ email: "chirag@example.com"
120
+ });
121
+
122
+ kit.checkIn(ticket.ticketId);
123
+
124
+ const result = kit.checkOut(ticket.ticketId);
125
+
126
+ assert.equal(result.success, true);
127
+ assert.equal(result.ticket.status, "checked-out");
128
+ assert.ok(result.ticket.checkedOutAt);
129
+ });
130
+
131
+ test("rejects registration when event is full", () => {
132
+ const kit = new CheckInKit({
133
+ eventName: "Tech Fest",
134
+ capacity: 1
135
+ });
136
+
137
+ kit.registerAttendee({
138
+ name: "Chirag",
139
+ email: "chirag@example.com"
140
+ });
141
+
142
+ assert.throws(() => {
143
+ kit.registerAttendee({
144
+ name: "Aryan",
145
+ email: "aryan@example.com"
146
+ });
147
+ }, /Event is full/);
148
+ });