{"_id":"@abhi1705/xray-sdk","_rev":"19-e31afac0679739e4ac4432c1b412a37d","name":"@abhi1705/xray-sdk","dist-tags":{"latest":"1.0.4"},"versions":{"1.0.1":{"name":"@abhi1705/xray-sdk","version":"1.0.1","keywords":["x-ray","loggers","debugging","dashboard","sdk","steps","executions","pipeline"],"author":{"name":"abhijain1705"},"license":"ISC","_id":"@abhi1705/xray-sdk@1.0.1","maintainers":[{"name":"abhi1705","email":"abhijain3002@gmail.com"}],"homepage":"https://github.com/abhijain1705/X-Ray#readme","bugs":{"url":"https://github.com/abhijain1705/X-Ray/issues"},"dist":{"shasum":"6f29bdf158e93cc1700c8cae3633aa2ef245370a","tarball":"https://registry.npmjs.org/@abhi1705/xray-sdk/-/xray-sdk-1.0.1.tgz","fileCount":5,"integrity":"sha512-CJEZNcWSvuH9vHSLSt5rPFAs8UzKyXaUh/6G1Im+2gUKAArMDDbppLnWs8KQleszi6QTRgdqguDY9BlF4pe8xQ==","signatures":[{"sig":"MEUCIQCMNWsmpmyQpaQZafKscqnQpXDvJbdS3jRXOFcADCM2BQIgAR7Su9japOFHpS+EU5Y/ngVPA7ThA4iPYoRPlS2WuJ0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":10410},"main":"src/index.ts","gitHead":"74514b8adb95149dcd207c313db0eeab9c097d6e","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"abhi1705","email":"abhijain3002@gmail.com"},"deprecated":"Use 1.0.3+","repository":{"url":"git+https://github.com/abhijain1705/X-Ray.git","type":"git"},"_npmVersion":"10.9.3","description":"X-Ray is a lightweight SDK + backend that records multi-step decision executions, persists them, and visualizes timelines in a dashboard. It's designed for systems where you need visibility into how decisions were made without incurring the overhead of ev","directories":{},"_nodeVersion":"22.19.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/xray-sdk_1.0.1_1766930992395_0.17813968505146693","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@abhi1705/xray-sdk","version":"1.0.4","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"build":"bun build src/index.ts --outdir dist --target node --dts","prepublishOnly":"bun run build","dev":"bun build src/index.ts --outdir dist --watch"},"dependencies":{"dotenv":"^17.2.3"},"gitHead":"3a4d1321358a20ef3d07beb44ce13ef56e65f0c2","_id":"@abhi1705/xray-sdk@1.0.4","description":"A lightweight TypeScript SDK for recording and visualizing multi-step decision executions. X-Ray provides visibility into how complex decisions are made in your applications without requiring heavy infrastructure or event streaming systems.","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-SEgIsxN80DAX3QGiz0FTppFjgZOHtfU/fvkt0VqJYxwzg6MddceGCOV/ZQb0+rylSm79/+f69f5PHfSpxk+eJg==","shasum":"188ddc78113b229c9989aac7ad858671d38643df","tarball":"https://registry.npmjs.org/@abhi1705/xray-sdk/-/xray-sdk-1.0.4.tgz","fileCount":11,"unpackedSize":32744,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEwKxN74XnSdlDpxuFHwtw15xjnjlq90yENT8uzrzMxvAiEArTEwVIbHcuz149FY+7dZV0oErqNRp45keQpYeizdBgM="}]},"_npmUser":{"name":"abhi1705","email":"abhijain3002@gmail.com"},"directories":{},"maintainers":[{"name":"abhi1705","email":"abhijain3002@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/xray-sdk_1.0.4_1767274128906_0.0009395096630275823"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-28T14:06:23.991Z","modified":"2026-01-01T13:28:49.225Z","1.0.0":"2025-12-28T14:06:24.216Z","1.0.1":"2025-12-28T14:09:52.533Z","1.0.2":"2025-12-28T14:12:09.767Z","1.0.3":"2025-12-28T14:17:16.453Z","1.0.5":"2025-12-30T17:08:36.101Z","1.0.6":"2025-12-30T17:15:15.737Z","1.0.7":"2025-12-30T17:20:11.136Z","1.0.8":"2025-12-30T17:22:55.205Z","1.0.4":"2026-01-01T13:28:49.052Z"},"description":"A lightweight TypeScript SDK for recording and visualizing multi-step decision executions. X-Ray provides visibility into how complex decisions are made in your applications without requiring heavy infrastructure or event streaming systems.","maintainers":[{"name":"abhi1705","email":"abhijain3002@gmail.com"}],"readme":"# X-Ray SDK\r\n\r\nA lightweight TypeScript SDK for recording and visualizing multi-step decision executions. X-Ray provides visibility into how complex decisions are made in your applications without requiring heavy infrastructure or event streaming systems.\r\n\r\n## Overview\r\n\r\nX-Ray SDK integrates seamlessly into your application to:\r\n\r\n- Record multi-step execution flows in real-time\r\n- Capture input, output, and reasoning at each step\r\n- Track execution metadata and timestamps\r\n- Send execution data to the X-Ray backend for visualization and analysis\r\n\r\nPerfect for loan approval pipelines, competitor selection algorithms, or any multi-step decision system.\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @abhi1705/xray-sdk\r\n```\r\n\r\n## Quick Start\r\n\r\n### 1. Initialize the SDK\r\n\r\n```typescript\r\nimport { XRaySDK } from \"@abhi1705/xray-sdk\";\r\n\r\nconst sdk = new XRaySDK({\r\n  apiKey: \"your-api-key\",\r\n  appId: \"your-app-id\",\r\n  pipeline: \"loan-approval\",\r\n  environment: \"prod\", // optional: 'dev' or 'prod', defaults to 'prod'\r\n});\r\n```\r\n\r\n### 2. Start an Execution\r\n\r\n```typescript\r\nconst execution = sdk.startExecution();\r\n```\r\n\r\n### 3. Record Steps\r\n\r\n```typescript\r\nexecution.recordStep({\r\n  name: \"credit-check\",\r\n  status: \"in_progress\",\r\n  input: { applicantId: \"12345\" },\r\n  reasoning: \"Validating credit score\",\r\n});\r\n\r\n// ... perform your logic ...\r\n\r\nexecution.recordStep({\r\n  name: \"credit-check\",\r\n  status: \"completed\",\r\n  output: { creditScore: 750, approved: true },\r\n  metadata: { source: \"equifax\" },\r\n});\r\n```\r\n\r\n### 4. Complete Execution\r\n\r\n```typescript\r\nexecution.complete();\r\n\r\n// or with failure\r\nexecution.fail({\r\n  error: \"Credit check failed\",\r\n  reason: \"API timeout\",\r\n});\r\n```\r\n\r\n## Configuration\r\n\r\n### StaticConfig\r\n\r\nThe SDK requires the following configuration:\r\n\r\n```typescript\r\ntype StaticConfig = {\r\n  apiKey: string; // Your API key from X-Ray dashboard\r\n  appId: string; // Application identifier\r\n  pipeline: string; // Pipeline name (e.g., 'loan-approval')\r\n  environment?: \"dev\" | \"prod\"; // Optional, defaults to 'prod'\r\n};\r\n```\r\n\r\n## API Reference\r\n\r\n### XRaySDK\r\n\r\n#### Constructor\r\n\r\n```typescript\r\nconstructor(config: StaticConfig)\r\n```\r\n\r\nInitializes the SDK with your configuration. Throws an error if `apiKey`, `appId`, or `pipeline` are missing.\r\n\r\n#### Methods\r\n\r\n- **`startExecution()`**: Begins a new execution flow and returns an execution handler\r\n\r\n### Execution Object\r\n\r\n#### Methods\r\n\r\n- **`recordStep(step: StepInput)`**: Records a step in the execution\r\n- **`complete()`**: Marks execution as successfully completed\r\n- **`fail(error: { error: string; reason?: string })`**: Marks execution as failed\r\n\r\n### StepInput\r\n\r\n```typescript\r\ntype StepInput = {\r\n  name: string; // Step name/identifier\r\n  timestamp?: number; // Optional timestamp (ms), auto-generated if omitted\r\n  status?: \"pending\" | \"in_progress\" | \"completed\" | \"failed\"; // Step status\r\n  input?: unknown; // Step input data\r\n  output?: unknown; // Step output data\r\n  reasoning?: string; // Why this step was taken\r\n  metadata?: Record<string, any>; // Additional metadata\r\n};\r\n```\r\n\r\n## Usage Examples\r\n\r\n### Loan Approval Pipeline\r\n\r\n```typescript\r\nimport { XRaySDK } from \"@abhi1705/xray-sdk\";\r\n\r\nconst sdk = new XRaySDK({\r\n  apiKey: \"sk_live_123456\",\r\n  appId: \"lending-platform\",\r\n  pipeline: \"loan-approval\",\r\n});\r\n\r\nasync function approveLoan(applicantData) {\r\n  const execution = sdk.startExecution();\r\n\r\n  try {\r\n    // Step 1: Credit Check\r\n    execution.recordStep({\r\n      name: \"credit-check\",\r\n      status: \"in_progress\",\r\n      input: { applicantId: applicantData.id },\r\n    });\r\n\r\n    const creditScore = await checkCredit(applicantData.id);\r\n\r\n    execution.recordStep({\r\n      name: \"credit-check\",\r\n      status: \"completed\",\r\n      output: { creditScore },\r\n      reasoning: \"Retrieved credit score from Equifax\",\r\n    });\r\n\r\n    // Step 2: Income Verification\r\n    execution.recordStep({\r\n      name: \"income-verification\",\r\n      status: \"in_progress\",\r\n    });\r\n\r\n    const income = await verifyIncome(applicantData);\r\n\r\n    execution.recordStep({\r\n      name: \"income-verification\",\r\n      status: \"completed\",\r\n      output: { monthlyIncome: income },\r\n    });\r\n\r\n    // Step 3: Risk Assessment\r\n    const decision = assessRisk({\r\n      creditScore,\r\n      income,\r\n      loanAmount: applicantData.loanAmount,\r\n    });\r\n\r\n    execution.recordStep({\r\n      name: \"risk-assessment\",\r\n      status: \"completed\",\r\n      output: { riskLevel: decision.risk, approved: decision.approved },\r\n      reasoning: `Credit: ${creditScore}, Income: ${income}, Risk: ${decision.risk}`,\r\n    });\r\n\r\n    execution.complete();\r\n    return decision;\r\n  } catch (error) {\r\n    execution.fail({\r\n      error: error.message,\r\n      reason: \"Processing error in loan approval\",\r\n    });\r\n    throw error;\r\n  }\r\n}\r\n```\r\n\r\n### Competitor Selection Pipeline\r\n\r\n```typescript\r\nconst execution = sdk.startExecution();\r\n\r\nexecution.recordStep({\r\n  name: \"market-analysis\",\r\n  status: \"completed\",\r\n  output: { competitors: [\"Company A\", \"Company B\"] },\r\n  metadata: { analysisVersion: \"2.1\", region: \"US\" },\r\n});\r\n\r\nexecution.recordStep({\r\n  name: \"competitor-ranking\",\r\n  status: \"completed\",\r\n  output: { ranked: [\"Company A\", \"Company B\"] },\r\n  reasoning: \"Ranked by market share and innovation score\",\r\n});\r\n\r\nexecution.complete();\r\n```\r\n\r\n## Error Handling\r\n\r\nThe SDK automatically handles:\r\n\r\n- Network failures (gracefully swallows errors to avoid blocking your application)\r\n- Invalid configuration (throws on SDK initialization)\r\n\r\nAlways wrap execution logic in try-catch blocks for proper error handling:\r\n\r\n```typescript\r\ntry {\r\n  const execution = sdk.startExecution();\r\n  // ... record steps ...\r\n  execution.complete();\r\n} catch (error) {\r\n  console.error(\"Execution failed:\", error);\r\n  // Handle error appropriately\r\n}\r\n```\r\n\r\n## Environment Setup\r\n\r\nSet the server API endpoint via environment variable:\r\n\r\n```bash\r\nexport SERVER_API=\"https://your-xray-backend.com\"\r\n```\r\n\r\n## Data Privacy\r\n\r\nX-Ray SDK:\r\n\r\n- Only sends data when explicitly recorded via `recordStep()`\r\n- Respects your `input`, `output`, and `metadata` structure\r\n- Transmits data over HTTPS to the configured backend\r\n- Does not track or store sensitive data beyond what you provide\r\n\r\n## Support & Feedback\r\n\r\n- **GitHub Issues**: [Report bugs or suggest features](https://github.com/abhijain1705/X-Ray/issues)\r\n- **Documentation**: [Full API docs](https://github.com/abhijain1705/X-Ray/tree/main/docs)\r\n- **Dashboard**: Visualize your executions in the X-Ray dashboard\r\n\r\n## License\r\n\r\nISC - See LICENSE file for details\r\n\r\n## Version\r\n\r\nCurrent version: 1.0.0\r\n","readmeFilename":"Readme.md"}