{"_id":"@conveniencepro/ctp-sdk","name":"@conveniencepro/ctp-sdk","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@conveniencepro/ctp-sdk","version":"1.0.0","description":"Embeddable SDK for ConveniencePro tools - integrate CTP tools into any website","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","browser":"dist/sdk.global.js","unpkg":"dist/sdk.global.js","jsdelivr":"dist/sdk.global.js","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.js","types":"./dist/index.d.ts"},"./embed":{"import":"./dist/embed.mjs","require":"./dist/embed.js","types":"./dist/embed.d.ts"},"./autosense":{"import":"./dist/autosense.mjs","require":"./dist/autosense.js","types":"./dist/autosense.d.ts"}},"scripts":{"build":"tsup src/index.ts src/embed.ts src/autosense.ts --format cjs,esm --dts --clean && tsup src/sdk.global.ts --format iife --globalName ConveniencePro --minify","dev":"tsup src/index.ts src/embed.ts src/autosense.ts --format cjs,esm --dts --watch","test":"vitest run","test:watch":"vitest","lint":"eslint src --ext .ts","clean":"rm -rf dist"},"keywords":["ctp","conveniencepro","sdk","embed","iframe","widget","tools"],"author":{"name":"ConveniencePro"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/titan-alpha/ctp.git","directory":"packages/ctp-sdk"},"homepage":"https://spec.conveniencepro.cc","bugs":{"url":"https://github.com/titan-alpha/ctp/issues"},"dependencies":{"@conveniencepro/ctp-core":"^1.0.0"},"devDependencies":{"@types/node":"^20.0.0","tsup":"^8.0.0","typescript":"^5.3.0","vitest":"^1.0.0"},"engines":{"node":">=16.0.0"},"gitHead":"e0b486c2f3a42f11091b47050f6c7c043393374b","_id":"@conveniencepro/ctp-sdk@1.0.0","_nodeVersion":"25.1.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-QySfhVMrDf/E3UHzY8/jbTKmqPcSuSFjvDxPy+gRoP36HYSqs+U2mLCDH+eikC6Y61M3awKBeXnhwRdGNwsV+A==","shasum":"e7070c733da0d1818ba64e6043cb292a529334bc","tarball":"https://registry.npmjs.org/@conveniencepro/ctp-sdk/-/ctp-sdk-1.0.0.tgz","fileCount":17,"unpackedSize":89173,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAVNf7IM7abICHODvo8/b+Nhx8r9Hl+JuMGdvvX3bOd7AiEA/+xQHtkOWBSGDwMPhvjhze7X5FYC1G2HZ2MZfHMnyoo="}]},"_npmUser":{"name":"convenienceprouser","email":"welovegoodhouse@gmail.com"},"directories":{},"maintainers":[{"name":"convenienceprouser","email":"welovegoodhouse@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ctp-sdk_1.0.0_1764822771949_0.6206542879376744"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-04T04:32:51.892Z","1.0.0":"2025-12-04T04:32:52.113Z","modified":"2025-12-04T04:32:52.370Z"},"maintainers":[{"name":"convenienceprouser","email":"welovegoodhouse@gmail.com"}],"description":"Embeddable SDK for ConveniencePro tools - integrate CTP tools into any website","homepage":"https://spec.conveniencepro.cc","keywords":["ctp","conveniencepro","sdk","embed","iframe","widget","tools"],"repository":{"type":"git","url":"git+https://github.com/titan-alpha/ctp.git","directory":"packages/ctp-sdk"},"author":{"name":"ConveniencePro"},"bugs":{"url":"https://github.com/titan-alpha/ctp/issues"},"license":"MIT","readme":"# @conveniencepro/ctp-sdk\n\nEmbeddable SDK for **ConveniencePro Tool Protocol (CTP)** tools.\n\nIntegrate CTP tools into any website with automatic style matching and theme detection.\n\n## Installation\n\n### NPM/Yarn\n\n```bash\nnpm install @conveniencepro/ctp-sdk\n# or\nyarn add @conveniencepro/ctp-sdk\n```\n\n### CDN (Browser)\n\n```html\n<script src=\"https://cdn.jsdelivr.net/npm/@conveniencepro/ctp-sdk/dist/sdk.global.js\"></script>\n```\n\nOr use unpkg:\n\n```html\n<script src=\"https://unpkg.com/@conveniencepro/ctp-sdk/dist/sdk.global.js\"></script>\n```\n\n## Quick Start\n\n### Method 1: Auto-Discovery (Easiest)\n\n```html\n<!-- Add data attributes to your container -->\n<div data-ctp-tool=\"json-formatter\"></div>\n\n<!-- Include the SDK (it auto-initializes) -->\n<script src=\"https://cdn.jsdelivr.net/npm/@conveniencepro/ctp-sdk\"></script>\n```\n\n### Method 2: Programmatic\n\n```html\n<div id=\"tool-container\"></div>\n\n<script src=\"https://cdn.jsdelivr.net/npm/@conveniencepro/ctp-sdk\"></script>\n<script>\n  ConveniencePro.embed('tool-container', 'json-formatter', {\n    theme: 'dark',\n    accentColor: '#ff5500',\n  });\n</script>\n```\n\n### Method 3: ES Module\n\n```typescript\nimport { embed } from '@conveniencepro/ctp-sdk';\n\nconst controller = embed('container', 'json-formatter', {\n  autosense: true,\n  onReady: (ctrl) => console.log('Embed ready!'),\n  onResult: (result) => console.log('Result:', result),\n});\n```\n\n## Features\n\n### Autosense\n\nAutomatically detect and match the host page's styling:\n\n```typescript\nimport { embed, detectStyles } from '@conveniencepro/ctp-sdk';\n\n// Auto-detect styles (default behavior)\nembed('container', 'tool-id', { autosense: true });\n\n// Manual detection\nconst styles = detectStyles(document.body);\nconsole.log(styles);\n// {\n//   theme: 'dark',\n//   accentColor: '#6366f1',\n//   fontFamily: 'Inter, sans-serif',\n//   borderRadius: 8,\n//   framework: 'tailwind',\n//   ...\n// }\n```\n\n### Theme Watching\n\nAutomatically update when the page theme changes:\n\n```typescript\nembed('container', 'tool-id', {\n  autosense: true,\n  watchTheme: true, // React to theme changes\n});\n```\n\n### Framework Detection\n\nThe SDK detects these CSS frameworks:\n- Tailwind CSS\n- Bootstrap\n- Chakra UI\n- Material UI (MUI)\n- shadcn/ui\n- Ant Design\n\n## Configuration\n\n### Data Attributes\n\n```html\n<div\n  data-ctp-tool=\"json-formatter\"\n  data-ctp-base-url=\"https://conveniencepro.cc\"\n  data-ctp-theme=\"dark\"\n  data-ctp-accent=\"#ff5500\"\n  data-ctp-width=\"100%\"\n  data-ctp-height=\"500px\"\n  data-ctp-min-height=\"400px\"\n  data-ctp-autosense=\"true\"\n  data-ctp-watch-theme=\"true\"\n></div>\n```\n\n### JavaScript Options\n\n```typescript\ninterface EmbedConfig {\n  // Tool configuration\n  toolId?: string;\n  baseUrl?: string;\n  embedPath?: string;\n\n  // Dimensions\n  width?: string | number;\n  height?: string | number;\n  minHeight?: string | number;\n\n  // Styling (override autosense)\n  theme?: 'light' | 'dark';\n  accentColor?: string;\n  backgroundColor?: string;\n  textColor?: string;\n  fontFamily?: string;\n  baseFontSize?: number;\n  borderRadius?: number;\n  shadow?: 'none' | 'subtle' | 'medium' | 'large';\n  density?: 'compact' | 'normal' | 'comfortable';\n\n  // Behavior\n  autosense?: boolean;      // Auto-detect styles (default: true)\n  watchTheme?: boolean;     // Watch for theme changes (default: true)\n  loading?: 'lazy' | 'eager';\n  allowClipboard?: boolean;\n\n  // Callbacks\n  onReady?: (embed: EmbedController) => void;\n  onResult?: (result: unknown) => void;\n  onError?: (error: Error) => void;\n}\n```\n\n## Embed Controller\n\nThe `embed()` function returns a controller for managing the embed:\n\n```typescript\nconst controller = embed('container', 'tool-id');\n\n// Check if ready\nconsole.log(controller.ready);\n\n// Update styles dynamically\ncontroller.updateStyles({\n  theme: 'dark',\n  accentColor: '#ff0000',\n});\n\n// Reload the embed\ncontroller.reload();\n\n// Destroy the embed\ncontroller.destroy();\n```\n\n## Managing Multiple Embeds\n\n```typescript\nimport {\n  embed,\n  getEmbed,\n  getAllEmbeds,\n  destroyAllEmbeds,\n} from '@conveniencepro/ctp-sdk';\n\n// Create multiple embeds\nconst embed1 = embed('container1', 'json-formatter');\nconst embed2 = embed('container2', 'base64-encoder');\n\n// Get an embed by ID\nconst found = getEmbed(embed1.id);\n\n// Get all active embeds\nconst all = getAllEmbeds();\n\n// Destroy all embeds\ndestroyAllEmbeds();\n```\n\n## Style Detection Utilities\n\n```typescript\nimport {\n  detectStyles,\n  detectColorScheme,\n  detectFramework,\n  detectAccentColor,\n  detectFontFamily,\n  detectBorderRadius,\n  createThemeObserver,\n} from '@conveniencepro/ctp-sdk';\n\n// Detect individual properties\nconst theme = detectColorScheme();       // 'light' | 'dark'\nconst framework = detectFramework();      // 'tailwind' | 'bootstrap' | ...\nconst accent = detectAccentColor();       // '#6366f1'\nconst font = detectFontFamily();          // 'Inter, sans-serif'\nconst radius = detectBorderRadius();      // 8\n\n// Watch for theme changes\nconst unsubscribe = createThemeObserver((newTheme) => {\n  console.log('Theme changed to:', newTheme);\n});\n\n// Stop watching\nunsubscribe();\n```\n\n## Available Tools\n\nPopular tools you can embed:\n\n| Tool ID | Description |\n|---------|-------------|\n| `json-formatter` | Format and beautify JSON |\n| `base64-encoder` | Base64 encoding/decoding |\n| `hash-generator` | SHA-256, MD5, etc. |\n| `uuid-generator` | Generate UUIDs |\n| `color-converter` | Convert between color formats |\n| `regex-tester` | Test regular expressions |\n| `case-converter` | Convert text case |\n| `timestamp-converter` | Unix/ISO timestamp conversion |\n\nSee the full list at [conveniencepro.cc/tools](https://conveniencepro.cc/tools).\n\n## Examples\n\n### React\n\n```tsx\nimport { useEffect, useRef } from 'react';\nimport { embed, EmbedController } from '@conveniencepro/ctp-sdk';\n\nfunction ToolEmbed({ toolId }: { toolId: string }) {\n  const containerRef = useRef<HTMLDivElement>(null);\n  const controllerRef = useRef<EmbedController | null>(null);\n\n  useEffect(() => {\n    if (containerRef.current) {\n      controllerRef.current = embed(containerRef.current, toolId, {\n        autosense: true,\n      });\n    }\n\n    return () => {\n      controllerRef.current?.destroy();\n    };\n  }, [toolId]);\n\n  return <div ref={containerRef} />;\n}\n```\n\n### Vue\n\n```vue\n<template>\n  <div ref=\"container\"></div>\n</template>\n\n<script setup lang=\"ts\">\nimport { ref, onMounted, onUnmounted } from 'vue';\nimport { embed, type EmbedController } from '@conveniencepro/ctp-sdk';\n\nconst container = ref<HTMLElement>();\nlet controller: EmbedController | null = null;\n\nonMounted(() => {\n  if (container.value) {\n    controller = embed(container.value, 'json-formatter');\n  }\n});\n\nonUnmounted(() => {\n  controller?.destroy();\n});\n</script>\n```\n\n## Related Packages\n\n- `@conveniencepro/ctp-core` - Core types and interfaces\n- `@conveniencepro/ctp-runtime` - Tool execution runtime\n- `@conveniencepro/ctp-discovery` - Manifest generation\n\n## License\n\nMIT © ConveniencePro\n","readmeFilename":"README.md","_rev":"1-90cbf7192a15d841569085d10dd384a9"}