copyleaks 5.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.
Files changed (157) hide show
  1. checksums.yaml +7 -0
  2. data/.gitignore +17 -0
  3. data/CHANGELOG.md +102 -0
  4. data/Gemfile +5 -0
  5. data/LICENSE.txt +21 -0
  6. data/README.md +487 -0
  7. data/Rakefile +13 -0
  8. data/bin/console +11 -0
  9. data/bin/setup +8 -0
  10. data/lib/copyleaks/ai_detection_client.rb +27 -0
  11. data/lib/copyleaks/ai_image_detection_client.rb +35 -0
  12. data/lib/copyleaks/ai_video_detection_client.rb +20 -0
  13. data/lib/copyleaks/api.rb +247 -0
  14. data/lib/copyleaks/app.config.rb +36 -0
  15. data/lib/copyleaks/image_plagiarism_client.rb +19 -0
  16. data/lib/copyleaks/models/aiDetection/responses/CopyleaksAiTextDetectionExplainModel.rb +26 -0
  17. data/lib/copyleaks/models/aiDetection/responses/CopyleaksAiTextDetectionMatchModel.rb +33 -0
  18. data/lib/copyleaks/models/aiDetection/responses/CopyleaksAiTextDetectionMatchTextModel.rb +31 -0
  19. data/lib/copyleaks/models/aiDetection/responses/CopyleaksAiTextDetectionPatternMatchModel.rb +32 -0
  20. data/lib/copyleaks/models/aiDetection/responses/CopyleaksAiTextDetectionPatternStatisticsModel.rb +46 -0
  21. data/lib/copyleaks/models/aiDetection/responses/CopyleaksAiTextDetectionPatternsModel.rb +38 -0
  22. data/lib/copyleaks/models/aiDetection/responses/CopyleaksAiTextDetectionPositionsModel.rb +39 -0
  23. data/lib/copyleaks/models/aiDetection/responses/CopyleaksAiTextDetectionResponseModel.rb +68 -0
  24. data/lib/copyleaks/models/aiDetection/responses/CopyleaksAiTextDetectionResultModel.rb +41 -0
  25. data/lib/copyleaks/models/aiDetection/responses/CopyleaksAiTextDetectionScannedDocumentModel.rb +21 -0
  26. data/lib/copyleaks/models/aiDetection/responses/CopyleaksAiTextDetectionSummaryModel.rb +34 -0
  27. data/lib/copyleaks/models/auth_token.rb +46 -0
  28. data/lib/copyleaks/models/constants/CopyleaksAiImageDetectionModels.rb +5 -0
  29. data/lib/copyleaks/models/constants/CopyleaksAiImageMaskTypes.rb +11 -0
  30. data/lib/copyleaks/models/constants/CopyleaksAiVideoDetectionModels.rb +5 -0
  31. data/lib/copyleaks/models/constants/CopyleaksAlertCodes.rb +7 -0
  32. data/lib/copyleaks/models/constants/CopyleaksTextModerationConstants.rb +15 -0
  33. data/lib/copyleaks/models/constants/CopyleaksTextModerationLanguages.rb +6 -0
  34. data/lib/copyleaks/models/constants/index.rb +10 -0
  35. data/lib/copyleaks/models/delete_request_model.rb +50 -0
  36. data/lib/copyleaks/models/exceptions/auth_expired_exception.rb +7 -0
  37. data/lib/copyleaks/models/exceptions/command_exception.rb +13 -0
  38. data/lib/copyleaks/models/exceptions/copyleaks_api_exception.rb +18 -0
  39. data/lib/copyleaks/models/exceptions/index.rb +8 -0
  40. data/lib/copyleaks/models/exceptions/rate_limit_exception.rb +8 -0
  41. data/lib/copyleaks/models/exceptions/under_maintenance_exception.rb +8 -0
  42. data/lib/copyleaks/models/exports/export_crawled_version.rb +6 -0
  43. data/lib/copyleaks/models/exports/export_model.rb +87 -0
  44. data/lib/copyleaks/models/exports/export_pdf_report.rb +6 -0
  45. data/lib/copyleaks/models/exports/export_results.rb +30 -0
  46. data/lib/copyleaks/models/exports/export_target.rb +42 -0
  47. data/lib/copyleaks/models/exports/index.rb +8 -0
  48. data/lib/copyleaks/models/id_object.rb +22 -0
  49. data/lib/copyleaks/models/imageDetection/requests/CopyleaksAiImageDetectionAsyncRequestModel.rb +63 -0
  50. data/lib/copyleaks/models/imageDetection/requests/CopyleaksAiImageDetectionRequestModel.rb +135 -0
  51. data/lib/copyleaks/models/imageDetection/requests/CopyleaksAsyncWebhooksModel.rb +37 -0
  52. data/lib/copyleaks/models/imageDetection/responses/CopyleaksAiImageDetectedObjectModel.rb +31 -0
  53. data/lib/copyleaks/models/imageDetection/responses/CopyleaksAiImageDetectionImageInfoModel.rb +31 -0
  54. data/lib/copyleaks/models/imageDetection/responses/CopyleaksAiImageDetectionResponseModel.rb +79 -0
  55. data/lib/copyleaks/models/imageDetection/responses/CopyleaksAiImageDetectionResultModel.rb +40 -0
  56. data/lib/copyleaks/models/imageDetection/responses/CopyleaksAiImageDetectionScannedDocumentModel.rb +46 -0
  57. data/lib/copyleaks/models/imageDetection/responses/CopyleaksAiImageDetectionSummaryModel.rb +33 -0
  58. data/lib/copyleaks/models/imageDetection/responses/CopyleaksImageMetadataModel.rb +45 -0
  59. data/lib/copyleaks/models/imageDetection/responses/CopyleaksImageShapeModel.rb +31 -0
  60. data/lib/copyleaks/models/imagePlagiarism/requests/CopyleaksImagePlagiarismRequestModel.rb +51 -0
  61. data/lib/copyleaks/models/imagePlagiarism/responses/CopyleaksImagePlagiarismResponseModel.rb +187 -0
  62. data/lib/copyleaks/models/index.rb +51 -0
  63. data/lib/copyleaks/models/start_request_model.rb +40 -0
  64. data/lib/copyleaks/models/submissions/ai_detection/ai_detection_submission_model.rb +25 -0
  65. data/lib/copyleaks/models/submissions/ai_detection/natural_language_submission_model.rb +41 -0
  66. data/lib/copyleaks/models/submissions/file_ocr_submission_model.rb +36 -0
  67. data/lib/copyleaks/models/submissions/file_submission_model.rb +35 -0
  68. data/lib/copyleaks/models/submissions/index.rb +16 -0
  69. data/lib/copyleaks/models/submissions/properties/actions.rb +10 -0
  70. data/lib/copyleaks/models/submissions/properties/ai_generated_text.rb +40 -0
  71. data/lib/copyleaks/models/submissions/properties/ai_generated_text_explain.rb +6 -0
  72. data/lib/copyleaks/models/submissions/properties/ai_source_match.rb +6 -0
  73. data/lib/copyleaks/models/submissions/properties/assignment.rb +6 -0
  74. data/lib/copyleaks/models/submissions/properties/author.rb +18 -0
  75. data/lib/copyleaks/models/submissions/properties/copyleaks_db.rb +22 -0
  76. data/lib/copyleaks/models/submissions/properties/course.rb +6 -0
  77. data/lib/copyleaks/models/submissions/properties/cross_languages.rb +21 -0
  78. data/lib/copyleaks/models/submissions/properties/custom_metadata.rb +19 -0
  79. data/lib/copyleaks/models/submissions/properties/domains_mode.rb +8 -0
  80. data/lib/copyleaks/models/submissions/properties/enable_flag.rb +26 -0
  81. data/lib/copyleaks/models/submissions/properties/exclude.rb +57 -0
  82. data/lib/copyleaks/models/submissions/properties/exclude_code.rb +19 -0
  83. data/lib/copyleaks/models/submissions/properties/filter.rb +49 -0
  84. data/lib/copyleaks/models/submissions/properties/index.rb +43 -0
  85. data/lib/copyleaks/models/submissions/properties/indexing.rb +25 -0
  86. data/lib/copyleaks/models/submissions/properties/indexing_repository.rb +26 -0
  87. data/lib/copyleaks/models/submissions/properties/institution.rb +6 -0
  88. data/lib/copyleaks/models/submissions/properties/internal_ai_source_match.rb +7 -0
  89. data/lib/copyleaks/models/submissions/properties/language.rb +18 -0
  90. data/lib/copyleaks/models/submissions/properties/masking_policy.rb +11 -0
  91. data/lib/copyleaks/models/submissions/properties/overview.rb +42 -0
  92. data/lib/copyleaks/models/submissions/properties/pdf_colors.rb +48 -0
  93. data/lib/copyleaks/models/submissions/properties/pdf_properties.rb +51 -0
  94. data/lib/copyleaks/models/submissions/properties/pdf_report_version.rb +9 -0
  95. data/lib/copyleaks/models/submissions/properties/pdf_version.rb +10 -0
  96. data/lib/copyleaks/models/submissions/properties/references.rb +26 -0
  97. data/lib/copyleaks/models/submissions/properties/repository.rb +18 -0
  98. data/lib/copyleaks/models/submissions/properties/scan_method_algorithm.rb +8 -0
  99. data/lib/copyleaks/models/submissions/properties/scanning.rb +44 -0
  100. data/lib/copyleaks/models/submissions/properties/scanning_exclude.rb +47 -0
  101. data/lib/copyleaks/models/submissions/properties/scanning_include.rb +25 -0
  102. data/lib/copyleaks/models/submissions/properties/scanning_repository.rb +23 -0
  103. data/lib/copyleaks/models/submissions/properties/sensitive_data_protection.rb +42 -0
  104. data/lib/copyleaks/models/submissions/properties/submission_properties.rb +179 -0
  105. data/lib/copyleaks/models/submissions/properties/webhooks.rb +42 -0
  106. data/lib/copyleaks/models/submissions/properties/writing_feedback.rb +30 -0
  107. data/lib/copyleaks/models/submissions/submission_model.rb +24 -0
  108. data/lib/copyleaks/models/submissions/url_submission_model.rb +41 -0
  109. data/lib/copyleaks/models/submissions/webhooks/CompletedWebhook.rb +67 -0
  110. data/lib/copyleaks/models/submissions/webhooks/CreditsCheckedWebhook.rb +24 -0
  111. data/lib/copyleaks/models/submissions/webhooks/ErrorWebhook.rb +22 -0
  112. data/lib/copyleaks/models/submissions/webhooks/ExportCompletedWebhook.rb +25 -0
  113. data/lib/copyleaks/models/submissions/webhooks/HelperModels/BaseModels/Metadata.rb +61 -0
  114. data/lib/copyleaks/models/submissions/webhooks/HelperModels/BaseModels/StatusWebhook.rb +23 -0
  115. data/lib/copyleaks/models/submissions/webhooks/HelperModels/BaseModels/Webhook.rb +25 -0
  116. data/lib/copyleaks/models/submissions/webhooks/HelperModels/CompletedModels/Notifications.rb +24 -0
  117. data/lib/copyleaks/models/submissions/webhooks/HelperModels/CompletedModels/Results.rb +54 -0
  118. data/lib/copyleaks/models/submissions/webhooks/HelperModels/CompletedModels/ScannedDocument.rb +36 -0
  119. data/lib/copyleaks/models/submissions/webhooks/HelperModels/ErrorModels/Error.rb +49 -0
  120. data/lib/copyleaks/models/submissions/webhooks/HelperModels/ExportModels/Task.rb +29 -0
  121. data/lib/copyleaks/models/submissions/webhooks/HelperModels/NewResultsModels/NewResultScore.rb +22 -0
  122. data/lib/copyleaks/models/submissions/webhooks/HelperModels/NewResultsModels/NewResultsInternet.rb +37 -0
  123. data/lib/copyleaks/models/submissions/webhooks/HelperModels/NewResultsModels/NewResultsRepositories.rb +28 -0
  124. data/lib/copyleaks/models/submissions/webhooks/HelperModels/NotificationsModels/Alerts.rb +91 -0
  125. data/lib/copyleaks/models/submissions/webhooks/HelperModels/ResultsModels/Batch.rb +26 -0
  126. data/lib/copyleaks/models/submissions/webhooks/HelperModels/ResultsModels/Database.rb +26 -0
  127. data/lib/copyleaks/models/submissions/webhooks/HelperModels/ResultsModels/Internet.rb +23 -0
  128. data/lib/copyleaks/models/submissions/webhooks/HelperModels/ResultsModels/Repositories.rb +36 -0
  129. data/lib/copyleaks/models/submissions/webhooks/HelperModels/ResultsModels/RepositoryMetadata.rb +11 -0
  130. data/lib/copyleaks/models/submissions/webhooks/HelperModels/ResultsModels/Score.rb +20 -0
  131. data/lib/copyleaks/models/submissions/webhooks/HelperModels/ResultsModels/SharedResultsModel.rb +22 -0
  132. data/lib/copyleaks/models/submissions/webhooks/HelperModels/ResultsModels/Tags.rb +12 -0
  133. data/lib/copyleaks/models/submissions/webhooks/IndexedWebhook.rb +9 -0
  134. data/lib/copyleaks/models/submissions/webhooks/NewResultWebhook.rb +32 -0
  135. data/lib/copyleaks/models/submissions/webhooks/index.rb +34 -0
  136. data/lib/copyleaks/models/submissions/writing_assistant/score_weights.rb +26 -0
  137. data/lib/copyleaks/models/submissions/writing_assistant/writing_assistant_submission_model.rb +32 -0
  138. data/lib/copyleaks/models/textModeration/requests/CopyleaksTextModerationLabel.rb +21 -0
  139. data/lib/copyleaks/models/textModeration/requests/CopyleaksTextModerationRequestModel.rb +45 -0
  140. data/lib/copyleaks/models/textModeration/responses/CopyleaksTextModerationResponseModel.rb +55 -0
  141. data/lib/copyleaks/models/textModeration/responses/submodules/ModerationsModel.rb +27 -0
  142. data/lib/copyleaks/models/textModeration/responses/submodules/Text.rb +27 -0
  143. data/lib/copyleaks/models/textModeration/responses/submodules/TextModerationChars.rb +32 -0
  144. data/lib/copyleaks/models/textModeration/responses/submodules/TextModerationScannedDocument.rb +55 -0
  145. data/lib/copyleaks/models/textModeration/responses/submodules/TextModerationsLegend.rb +29 -0
  146. data/lib/copyleaks/models/videoDetection/requests/CopyleaksAiVideoDetectionRequestModel.rb +61 -0
  147. data/lib/copyleaks/models/videoDetection/responses/CopyleaksAiVideoDetectionResponseModel.rb +177 -0
  148. data/lib/copyleaks/text_moderation_client.rb +18 -0
  149. data/lib/copyleaks/utils/copyleaks_client.utils.rb +101 -0
  150. data/lib/copyleaks/utils/http_client.rb +164 -0
  151. data/lib/copyleaks/utils/multipart.rb +86 -0
  152. data/lib/copyleaks/utils/status-code.utils.rb +23 -0
  153. data/lib/copyleaks/version.rb +3 -0
  154. data/lib/copyleaks/writing_assistant_client.rb +26 -0
  155. data/lib/copyleaks.rb +11 -0
  156. data/lib/index.rb +4 -0
  157. metadata +248 -0
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: bcadd0cda6153e0060a6c0b76f132fb7d4158070230eaea1d12d142cc4c3fbca
4
+ data.tar.gz: 4e0c9422af2856c51534e887857edf8868058f68da11dfd4bd3f3af0d64a262d
5
+ SHA512:
6
+ metadata.gz: 8ba98ab460dc615dd597f152d00364274143f67d7577aae2d1a7e0e7e20c98ade3cc820a0c330e3406785bff1b70175f37421d79631f093c81bdda144238c0d8
7
+ data.tar.gz: 96c8b2784d890de6dce26107af6387ba8879a1a38148c80da53c788bed613b403e482b6799fd4336a46a5f613be5f6a583a00f46404b714b9025cdf21bd9b884
data/.gitignore ADDED
@@ -0,0 +1,17 @@
1
+ /.bundle/
2
+ /.yardoc
3
+ /_yardoc/
4
+ /coverage/
5
+ /doc/
6
+ /pkg/
7
+ /spec/reports/
8
+ /tmp/
9
+
10
+ # Generated gem files
11
+ *.gem
12
+ plagiarism-checker-3.2.1.gem
13
+ plagiarism-checker-3.5.0.gem
14
+ plagiarism-checker-3.6.0.gem
15
+ plagiarism-checker-3.6.1.gem
16
+ plagiarism-checker-3.7.0.gem
17
+ plagiarism-checker-4.0.0.gem
data/CHANGELOG.md ADDED
@@ -0,0 +1,102 @@
1
+ # Changelog
2
+
3
+ All notable changes to the Copyleaks Ruby SDK are listed here.
4
+
5
+ ## 5.0.0
6
+
7
+ The gem is now published as `copyleaks`. Versions up to 4.1.1 were published as `plagiarism-checker`. The Ruby code you write does not change: `require 'copyleaks'` and the `Copyleaks` module are the same as before. Read the upgrade notes below.
8
+
9
+ ### Added
10
+
11
+ - **New submit properties.**
12
+ - `Copyleaks::SubmissionAiSourceMatch.new(true)`, passed as the new `aiSourceMatch` argument of `Copyleaks::SubmissionProperties`: finds online sources suspected of containing AI-generated text. It currently applies only to documents detected as English. When you leave it `nil`, the server default (disabled) applies.
13
+ - `displayLanguage` argument of `Copyleaks::SubmissionProperties`: the language of the scan's PDF report. One of `'en'`, `'es'`, `'pt'`, `'fr'`, `'de'`, `'it'` (lowercase, case-sensitive). The server default is `'en'`.
14
+ - `reportVersion` argument of `Copyleaks::SubmissionPDF`: which version of the PDF report to generate. One of `'v1'`, `'v2'`, `'v3'`, `'latest'` (lowercase, case-sensitive). It overrides `version` when both are set.
15
+ - The new arguments come after the existing ones and default to `nil`, so existing calls keep working. A value of the wrong type raises an error. A `nil` value is left out of the request.
16
+ - **AI alert in the completed webhook.**
17
+ - `Copyleaks::CompletedWebhook#ai_detection_alert` returns the `suspected-ai-text` alert as a `Copyleaks::Alerts`, or `nil` when the scan has no AI alert. It works whether `notifications` is the raw Hash from the webhook body or a `Copyleaks::Notifications` object. A malformed AI alert raises: `ArgumentError` when `severity` or `category` is missing, or `RuntimeError` when a field has the wrong type. The API always sends both fields.
18
+ - `Copyleaks::Alerts#ai_detection_result` and the shortcut `Copyleaks::CompletedWebhook#ai_detection_result` decode the alert's `additionalData` JSON string into a `Copyleaks::CopyleaksAiTextDetectionResponseModel`, with `summary.ai`, `summary.human`, `model_version`, `results`, `translation` and `explain`. They return `nil` when there is no AI alert, or when the data is empty or is JSON that is not an object. They raise `JSON::ParserError` when `additionalData` is not valid JSON. The raw string stays available as `alert.additionalData`.
19
+ - `Copyleaks::Alerts.from_json(hash)` builds an alert from a webhook alert Hash with String or Symbol keys.
20
+ - New constant `Copyleaks::CopyleaksAlertCodes::SUSPECTED_AI_TEXT` (`"suspected-ai-text"`).
21
+ - New AI Text Detection model classes, loaded by `require 'copyleaks'`.
22
+ - **Image Plagiarism Detection.** `api.image_plagiarism_client.check(token, scan_id, model)` searches the web for copies of an image. Build the request with `Copyleaks::CopyleaksImagePlagiarismRequestModel.new(image: File.binread(path), filename: 'photo.jpg', sandbox: true)`. The image is uploaded as multipart/form-data. `Copyleaks::CopyleaksImagePlagiarismResponseModel.from_json(result)` reads the matches.
23
+ - **AI Video Detection.** `api.ai_video_detection_client.submit(token, scan_id, model)` submits a video URL with `Copyleaks::CopyleaksAiVideoDetectionRequestModel` (`url:`, `filename:`, `model:`, `webhooks:`, and optional `headers:`, `verb:`, `sandbox:`, `developer_payload:`). The result is posted to your webhook; `Copyleaks::CopyleaksAiVideoDetectionResponseModel.from_json` reads it. New constant `Copyleaks::CopyleaksAiVideoDetectionModels::AI_VIDEO_1_PRO`.
24
+ - **Asynchronous AI Image Detection.** `api.ai_image_detection_client.submit_async(token, scan_id, model)` submits an image URL with `Copyleaks::CopyleaksAiImageDetectionAsyncRequestModel`. The result is posted to your webhook in the same shape as the synchronous result. `Copyleaks::CopyleaksAsyncWebhooksModel.new(url, headers)` sets the webhook for both asynchronous detectors.
25
+ - **New lookups.**
26
+ - `api.ai_detection_client.get_credits_balance(token)`: the AI Text Detection credit balance.
27
+ - `api.get_repository_info(token, repository_id)`: a Private Cloud Hub repository's credits, masking policy and status.
28
+ - `api.get_allowed_cross_languages` and `api.get_supported_ai_text_detection_file_types`. Both are public and need no login.
29
+ - **AI Image Detection options.**
30
+ - `mask_type:` (`Copyleaks::CopyleaksAiImageMaskTypes::BINARY`, `HEATMAP` or `NONE`) and `object_detection:` (up to 3 object names, for example `['face']`) on `Copyleaks::CopyleaksAiImageDetectionRequestModel`.
31
+ - `image:` sends the raw image bytes as multipart/form-data, without the base64 overhead. Pass `nil` as the base64 argument.
32
+ - `check` is a clearer alias of `submit_`.
33
+ - **AI Text Detection options.** `explain:` (AI Logic) and `sensitivity:` (1 to 3) on `Copyleaks::NaturalLanguageSubmissionModel`.
34
+ - **More scan properties.** All are optional and left out of the request when `nil`.
35
+ - Keyword arguments of `Copyleaks::SubmissionProperties`: `overview:` (`Copyleaks::SubmissionOverview`, Gen-AI Overview), `internalAiSourceMatch:` (`Copyleaks::SubmissionInternalAiSourceMatch`), `references:` (`Copyleaks::SubmissionReferences`, Citation Checker), `scanTimeZone:`, `course:`, `assignment:` and `institution:` (`Copyleaks::SubmissionCourse`, `SubmissionAssignment`, `SubmissionInstitution`).
36
+ - `sensitivity:` and `explain:` on `Copyleaks::SubmissionAiGeneratedText`.
37
+ - `include:` (`Copyleaks::SubmissionScanningInclude`) on `Copyleaks::SubmissionScanning`.
38
+ - `backlinksDomains:` and `text:` on `Copyleaks::SubmissionScanningExclude`.
39
+ - `copyleaksDb:` on `Copyleaks::SubmissionIndexing`.
40
+ - `aiDetection:` and `writingFeedback:` colors on `Copyleaks::SubmissionPdfColors`.
41
+ - Constants `Copyleaks::SubmissionPdfReportVersion` (`V1`, `V2`, `V3`, `LATEST`) and `Copyleaks::SubmissionPdfVersion::V3`.
42
+ - **More request fields.**
43
+ - `verb:` and `headers:` on `Copyleaks::CopyleaksURLSubmissionModel`, to scan pages that need a POST or custom headers.
44
+ - `headers:` on `Copyleaks::CopyleaksDeleteRequestModel`, for the completion webhook.
45
+ - Export targets `aiDetection:`, `writingFeedback:` and `overview:` on `Copyleaks::CopyleaksExportModel`, built with `Copyleaks::ExportAiDetection`, `ExportWritingFeedback` and `ExportOverview`.
46
+ - **More response and webhook fields.**
47
+ - AI Image Detection: `is_ai_detected`, `detected_objects`, `result.labels` (heatmap) and `image_info.metadata.content_summary`.
48
+ - AI Text Detection: `scanned_document`.
49
+ - Text Moderation: `model_version`.
50
+ - Completed webhook: `referencesValidation`, and `internalAIData` in `Copyleaks::Results`. New-result webhook: `internalAIData`.
51
+ - Error webhook: `type`, `id`, `url` and `details` in `Copyleaks::Error`.
52
+ - Failed asynchronous AI Image and AI Video Detection scans: `Copyleaks::CopyleaksAiImageDetectionResponseModel` and `Copyleaks::CopyleaksAiVideoDetectionResponseModel` have `error` (a `Copyleaks::Error`) and `developer_payload`, and `from_json` reads both. When a scan fails, the webhook has an `error` instead of a result, so check `error` first. `Copyleaks::Error.from_json(hash)` builds the error from a webhook `error` Hash.
53
+ - **Connection settings.** `Copyleaks::API.new` accepts `open_timeout:`, `read_timeout:`, `write_timeout:`, `keep_alive_timeout:`, `pool_size:`, `identity_server_uri:` and `api_server_uri:`. `api.close` closes idle connections.
54
+ - **Retry information.** `Copyleaks::RateLimitException` and `Copyleaks::UnderMaintenanceException` now carry the HTTP `response`, and `retry_after` returns the `Retry-After` header. All three API exceptions, `CommandException` included, now extend `Copyleaks::CopyleaksApiException`, which has `response` and `retry_after`.
55
+ - **Streamed usage history.** Pass a block to `get_usages_history_csv` to receive the CSV in chunks instead of one String.
56
+ - **Tests.** The repository has an offline test suite: `rake test`.
57
+
58
+ ### Changed
59
+
60
+ - **Gem renamed to `copyleaks`.** See the upgrade notes below.
61
+ - **The gem no longer installs the `console` and `setup` executables.** These are development scripts from the repository's `bin/` folder, and 4.x installed them as commands.
62
+ - **`Copyleaks::Alerts` accepts the webhook's own types.** `category` and `severity` can be Integers, as the webhook sends them. Strings are still accepted. `title`, `message`, `helpLink` and `additionalData` are now optional. `to_json` leaves out fields that are `nil`.
63
+ - **Connections are reused and safe to share between threads.** Each `Copyleaks::API` keeps a small pool of persistent connections, so a call no longer opens a new TCP and TLS connection, and one instance can be shared by Puma, Sidekiq or any threaded code.
64
+ - **Timeouts.** The defaults are 10 seconds to connect and 120 seconds to read or write, and you can change them. Earlier versions used fixed 60 second timeouts.
65
+ - **Requests are never resent automatically.** Earlier versions could upload a submit a second time after a read timeout, and the second upload failed with `409 Conflict`.
66
+ - **Unset fields are left out of requests.** Arguments that are not set now default to `nil` and are not sent, so the server default applies. This covers `Copyleaks::SubmissionFilter`, `SubmissionScanning`, `SubmissionExclude`, `SubmissionExcludeCode`, `SubmissionSensitiveData`, `SubmissionAiGeneratedText`, `SubmissionWritingFeedback`, the `sandbox` of the AI Text, AI Image, Grammar Checker and Text Moderation requests, and `purge` and `completionWebhook` of `Copyleaks::CopyleaksDeleteRequestModel`.
67
+ - **More arguments are optional.** `developerPayload`, `expiration` and `sensitivityLevel` of `Copyleaks::SubmissionProperties`; every argument of `Copyleaks::SubmissionPDF` and `Copyleaks::SubmissionScanningCopyleaksDB`; `repositories` of `Copyleaks::SubmissionIndexing`; `idPattern` of `Copyleaks::SubmissionScanningExclude`; `results` and `crawledVersion` of `Copyleaks::CopyleaksExportModel`; `code` and `message` of `Copyleaks::Error`; `scanId` of `Copyleaks::NewResultsInternet`.
68
+ - **Text Moderation accepts at most 16 labels**, the API limit. The earlier limit was 32.
69
+ - **AI Image Detection sends `filename`**, the documented field name, instead of `fileName`, and leaves out fields that are `nil`.
70
+ - **Supported file types** use the documented `/v3/miscellaneous/supported-plagiarism-file-types` path. The response is the same.
71
+ - **Login tokens.** `verify_auth_token` treats a token that expires within 5 minutes as expired, so it cannot expire in the middle of a request.
72
+ - **User-Agent** is now `ruby-sdk/5.0.0`.
73
+ - **Text Moderation response models** accept the parsed Hash that the client returns, as well as a JSON String.
74
+
75
+ ### Fixed
76
+
77
+ - **Usage history.** `Copyleaks::API#get_usages_history_csv` now returns the usage history as CSV text (a String). Earlier versions tried to parse the CSV as JSON and always raised `JSON::ParserError`.
78
+ - **Concurrent calls.** Calls made at the same time from several threads on one `Copyleaks::API` could fail with `IOError` or `EOFError`, or return another call's response.
79
+ - **AI Text Detection no longer prints every response** (`RES: ...`) to standard output.
80
+ - **PDF title color.** The second argument of `Copyleaks::SubmissionPdfColors` is now sent as `titles`, the documented name. Earlier versions sent `title`, which the API ignored.
81
+ - **Turning on one filter or scanning option no longer turns others off.** Building a `SubmissionFilter` only to set `safeSearch` used to turn off minor-change and related-meaning matching, and building a `SubmissionScanning` only to add a repository used to turn off internet scanning.
82
+ - **`Copyleaks::SubmissionProperties` no longer raises** when `developerPayload`, `expiration` or `sensitivityLevel` is left out.
83
+ - **Exports of a single artifact**, such as only the PDF report, no longer raise.
84
+ - **Special characters in ids.** Scan ids, export ids, repository ids and language codes are percent-encoded in the URL, and the usage history dates are encoded in the query string. An id with a space, `/`, `?`, `#` or `%` no longer breaks the request.
85
+ - **`login` checks the `key` argument.** Earlier versions checked `email` twice.
86
+ - **Building webhook models from webhook bodies.** `Copyleaks::Results` and `Copyleaks::Error` accept the newer webhook fields instead of raising `ArgumentError`, `Copyleaks::Internet` no longer requires a `scanId`, and `Copyleaks::CopyleaksTextModerationResponseModel.new` and `Copyleaks::TextModerationScannedDocument.new` no longer raise when no creation time is given.
87
+
88
+ ### Upgrade notes
89
+
90
+ - **Gemfile:** replace `gem 'plagiarism-checker'` with `gem 'copyleaks'`, then run `bundle install`. If you pin a version, use `gem 'copyleaks', '~> 5.0'`.
91
+ - **Command line:** `gem install copyleaks`. Then remove the old gem with `gem uninstall plagiarism-checker`.
92
+ - **Do not keep both gems.** Both gems ship `lib/copyleaks.rb`, so with both installed, `require 'copyleaks'` can load either one.
93
+ - **Your code:** `require 'copyleaks'`, the `Copyleaks` module and all class names stay the same. No code changes are needed for the rename.
94
+ - **Webhooks:** existing code that reads `notifications` or builds `Copyleaks::Alerts` keeps working. If you serialize an `Alerts` object, note that `nil` fields are now left out of the JSON.
95
+ - **Defaults of filters and scanning:** `Copyleaks::SubmissionFilter.new` used to send `minorChangesEnabled: false` and `relatedMeaningEnabled: false`, and `Copyleaks::SubmissionScanning.new` used to send `internet: false`. These fields are now left out, and the API default (`true`) applies. To keep them off, pass `false`, for example `Copyleaks::SubmissionFilter.new(true, false, false)` or `Copyleaks::SubmissionScanning.new(false)`.
96
+ - **Timeouts and retries:** the connect timeout is now 10 seconds (was 60) and the read timeout is 120 seconds (was 60). Pass `open_timeout:` or `read_timeout:` to `Copyleaks::API.new` to change them. Requests are no longer resent after a timeout or a dropped connection. If a submit raises a timeout, the scan may have been created: submitting again with the same scan id returns `409 Conflict`.
97
+ - **Text Moderation:** more than 16 labels raises `ArgumentError`. The API rejects such requests anyway.
98
+ - **AI Image Detection:** `CopyleaksAiImageDetectionRequestModel#to_hash` now uses the key `filename` (was `fileName`) and leaves out `nil` fields. A `sandbox` that is not `true`, `false` or `nil` raises `ArgumentError`.
99
+ - **Delete requests:** `Copyleaks::CopyleaksDeleteRequestModel#completionWebhook` returns `nil` (was `''`) when no webhook is set, and `purge` is sent only when you set it.
100
+ - **Login tokens:** `verify_auth_token`, and every call that checks the token, raises `Copyleaks::AuthExpiredException` 5 minutes before the token's expiry time. Log in again when it does.
101
+ - **Stricter types:** `Copyleaks::SubmissionScanning` raises when `internet` is not `true`, `false` or `nil`. `Copyleaks::ExportPdfReport` and `Copyleaks::ExportCrawledVersion` raise `RuntimeError` when `headers` is not `nil` or an Array of `[name, value]` String pairs (4.x sent any value).
102
+ - **Sub-clients:** if you build `AIDetectionClient`, `AIImageDetectionClient`, `TextModerationClient` or `WritingAssistantClient` yourself, they now use a `Copyleaks::HttpClient`. A `Net::HTTP` object is still accepted. Using `api.ai_detection_client` and the other accessors needs no change.
data/Gemfile ADDED
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ source 'https://rubygems.org'
4
+
5
+ gemspec
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License(MIT)
2
+
3
+ Copyright(c) 2016 Copyleaks LTD (https://copyleaks.com)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,487 @@
1
+ # Copyleaks SDK
2
+ The official [Copyleaks](https://copyleaks.com/) Ruby library.
3
+
4
+ Copyleaks is the integrity layer for your tech stack that helps organizations and individuals understand what's human-made and original, AI-generated, or manipulated across text, image, audio and video.
5
+
6
+ This SDK gives you access to the following Copyleaks products:
7
+
8
+ * AI Text Detection
9
+ * AI Image Detection (synchronous and asynchronous)
10
+ * AI Video Detection
11
+ * Plagiarism Checker (Authenticity scans: file, URL, OCR)
12
+ * Image Plagiarism Detection
13
+ * Grammar Checker
14
+ * Text Moderation
15
+ * Private Cloud Hub repository information
16
+
17
+ ## 🚀 Getting Started
18
+ Before you start, ensure you have the following:
19
+
20
+ * An active Copyleaks account. If you don’t have one, [sign up for free](https://copyleaks.com/signup).
21
+ * You can find your API key on the [API Dashboard](https://api.copyleaks.com/dashboard).
22
+
23
+ Once you have your account and API key:
24
+
25
+ **Install the SDK**:
26
+
27
+ Install using [RubyGems](https://rubygems.org/gems/copyleaks)
28
+ ```bash
29
+ gem install copyleaks
30
+ ```
31
+ Or add it to your Gemfile:
32
+ ```ruby
33
+ gem 'copyleaks'
34
+ ```
35
+ This gem was previously published as `plagiarism-checker`. To switch, replace `plagiarism-checker` with `copyleaks` in your Gemfile or install command. `require 'copyleaks'` stays the same.
36
+
37
+ ## 📚 Documentation
38
+ To learn more about how to use Copyleaks API please check out our [Documentation](https://docs.copyleaks.com/resources/sdks/ruby/).
39
+
40
+ ## Client options
41
+ `Copyleaks::API.new` takes optional keyword arguments. The defaults suit most applications.
42
+
43
+ ```ruby
44
+ copyleaks = Copyleaks::API.new(
45
+ open_timeout: 10, # seconds to connect (TCP and TLS)
46
+ read_timeout: 120, # seconds to wait for each read of a response
47
+ write_timeout: 120, # seconds to wait for each write of a request body (raise it for large uploads on slow links)
48
+ keep_alive_timeout: 30, # seconds an idle connection is kept for reuse
49
+ pool_size: 5 # maximum open connections per Copyleaks server
50
+ )
51
+ ```
52
+
53
+ - One `Copyleaks::API` instance is safe to share between threads (Puma, Sidekiq and other threaded servers). Each request uses its own pooled connection, and connections are reused between calls.
54
+ - Requests are never resent automatically. If a submit times out, the scan may still have been created: a second submit with the same scan id returns `409 Conflict`.
55
+ - `copyleaks.close` closes the idle connections. The client stays usable.
56
+ - `identity_server_uri:` and `api_server_uri:` override the server addresses for one client, without changing `Copyleaks::Config`.
57
+
58
+ ### Errors
59
+ - `Copyleaks::CommandException`: the server rejected the request. `e.response` holds the status code, headers and body.
60
+ - `Copyleaks::RateLimitException` (HTTP 429) and `Copyleaks::UnderMaintenanceException` (HTTP 503): retry later with exponential backoff. `e.retry_after` returns the `Retry-After` header when the server sends one.
61
+ - `Copyleaks::AuthExpiredException`: the login token has expired, or expires within 5 minutes. Log in again.
62
+ - `Copyleaks::CommandException`, `RateLimitException` and `UnderMaintenanceException` all extend `Copyleaks::CopyleaksApiException`, so one `rescue Copyleaks::CopyleaksApiException => e` catches any API error response.
63
+ - `Net::OpenTimeout`, `Net::ReadTimeout`, `Net::WriteTimeout` and socket errors: the request did not complete.
64
+
65
+ ## 💡 Usage Examples
66
+ Here are some common usage examples for the Copyleaks SDK. You can also see a comprehensive code example in the `demo.rb` file on our GitHub repository: [demo.rb](https://github.com/Copyleaks/Ruby-Plagiarism-Checker/blob/master/demo/demo.rb).
67
+
68
+ ### Get Authentication Token
69
+ This example demonstrates how to log in to the Copyleaks API and obtain an authentication token.
70
+
71
+ ```ruby
72
+ require 'copyleaks'
73
+ require 'base64'
74
+
75
+ # --- Your Credentials ---
76
+ USER_EMAIL = 'YOUR_EMAIL_ADDRESS'
77
+ USER_API_KEY = 'YOUR_API_KEY'
78
+ # --------------------
79
+
80
+ begin
81
+ # Log in to the Copyleaks API
82
+ puts "Authenticating..."
83
+ copyleaks = Copyleaks::API.new
84
+ auth_token = copyleaks.login(USER_EMAIL, USER_API_KEY)
85
+ puts "✅ Logged in successfully!"
86
+
87
+ end
88
+ ```
89
+ For a detailed understanding of the authentication process, refer to the Copyleaks Login Endpoint [Documentation](https://docs.copyleaks.com/reference/actions/account/login).
90
+ ##
91
+ ### Submit Text for Plagiarism Scan
92
+ This example shows how to prepare and submit raw text content for a plagiarism scan.
93
+
94
+ ```ruby
95
+ require 'copyleaks'
96
+ require 'base64'
97
+
98
+ # --- Your Credentials ---
99
+ USER_EMAIL = 'YOUR_EMAIL_ADDRESS'
100
+ USER_API_KEY = 'YOUR_API_KEY'
101
+ WEBHOOK_URL = 'https://your-server.com'
102
+ # --------------------
103
+
104
+ begin
105
+ scanId = DateTime.now.strftime('%Q').to_s
106
+ submisson = Copyleaks::CopyleaksFileSubmissionModel.new(
107
+ 'aGVsbG8gd29ybGQ=',
108
+ 'ruby.txt',
109
+ Copyleaks::SubmissionProperties.new(
110
+ Copyleaks::SubmissionWebhooks.new("#{WEBHOOK_URL}/webhook/{STATUS}","#{WEBHOOK_URL}/url-webhook/new-result"),
111
+ true,
112
+ 'developer_payloads_test',
113
+ true,
114
+ 60,
115
+ 1,
116
+ true,
117
+ Copyleaks::SubmissionActions::SCAN,
118
+ Copyleaks::SubmissionAuthor.new('Author_name'),
119
+ Copyleaks::SubmissionFilter.new(true, true, true),
120
+ Copyleaks::SubmissionScanning.new(true, nil, nil, Copyleaks::SubmissionScanningCopyleaksDB.new(true, true)),
121
+ Copyleaks::SubmissionIndexing.new([Copyleaks::SubmissionRepository.new('repo-1')]),
122
+ Copyleaks::SubmissionExclude.new(true, true, true, true, true),
123
+ Copyleaks::SubmissionPDF.new(true, 'pdf-title', BASE64_LOGO, false),
124
+ Copyleaks::SubmissionSensitiveData.new(false)
125
+ )
126
+ )
127
+
128
+ @copyleaks.submit_file(_authToken, scanId, submisson)
129
+
130
+ end
131
+ ```
132
+ For a full guide please refer to our step by step [Guide](https://docs.copyleaks.com/guides/authenticity/detect-plagiarism-text)
133
+
134
+ For a detailed understanding of the plagiarism detection process, refer to the Copyleaks Submit Endpoint [Documentation](https://docs.copyleaks.com/reference/actions/authenticity/submit-file)
135
+
136
+ Only `webhooks` is required in `Copyleaks::SubmissionProperties`. Every other argument is optional: a value left `nil` is not sent, and the server default applies. Newer options are keyword arguments:
137
+
138
+ ```ruby
139
+ properties = Copyleaks::SubmissionProperties.new(
140
+ Copyleaks::SubmissionWebhooks.new("#{WEBHOOK_URL}/webhook/{STATUS}"),
141
+ nil, nil, true, # includeHtml, developerPayload, sandbox
142
+ overview: Copyleaks::SubmissionOverview.new(true, ignoreAuthorData: true), # Gen-AI Overview
143
+ internalAiSourceMatch: Copyleaks::SubmissionInternalAiSourceMatch.new(true), # Internal AI Source Match
144
+ references: Copyleaks::SubmissionReferences.new(true), # Citation Checker
145
+ scanTimeZone: 'America/New_York', # time zone of the PDF report
146
+ course: Copyleaks::SubmissionCourse.new('course-1'),
147
+ assignment: Copyleaks::SubmissionAssignment.new('assignment-1'),
148
+ institution: Copyleaks::SubmissionInstitution.new('institution-1')
149
+ )
150
+ ```
151
+ Other new options:
152
+ - `Copyleaks::SubmissionAiGeneratedText.new(true, sensitivity: 2, explain: true)`: AI detection sensitivity (1 to 3) and AI Logic explanations
153
+ - `Copyleaks::SubmissionScanning.new(true, exclude, repositories, copyleaks_db, cross_languages, include: Copyleaks::SubmissionScanningInclude.new('my-prefix-*'))`
154
+ - `Copyleaks::SubmissionScanningExclude.new('draft-*', backlinksDomains: ['example.com'], text: ['Sample header'])`
155
+ - `Copyleaks::SubmissionIndexing.new(repositories, copyleaksDb: true)`
156
+ - `Copyleaks::SubmissionPdfColors.new(main_strip, titles, identical, minor_changes, related_meaning, aiDetection: '#FE5758', writingFeedback: '#FF9A02')`
157
+ - `Copyleaks::CopyleaksURLSubmissionModel.new(url, properties, verb: 'POST', headers: [['Cookie', 'session=abc']])`
158
+ - `Copyleaks::CopyleaksDeleteRequestModel.new(scans, true, 'https://your-server.com/deleted', headers: [['Authorization', 'Bearer token']])`
159
+
160
+ `copyleaks.get_allowed_cross_languages` lists the languages you can use with `Copyleaks::SubmissionCrossLanguages`, as maps of language name to code. For example, `copyleaks.get_allowed_cross_languages['resultLanguages'].values` returns the codes results can be found in. It needs no login.
161
+ ##
162
+ ### Export scan artifacts
163
+ Request any combination of artifacts. Only `completionWebhook` is required.
164
+
165
+ ```ruby
166
+ model = Copyleaks::CopyleaksExportModel.new(
167
+ 'https://your-server.com/export/completed',
168
+ nil, # results
169
+ nil, # crawledVersion
170
+ Copyleaks::ExportPdfReport.new('https://your-server.com/pdf', 'POST'),
171
+ aiDetection: Copyleaks::ExportAiDetection.new('https://your-server.com/ai', 'POST'),
172
+ writingFeedback: Copyleaks::ExportWritingFeedback.new('https://your-server.com/grammar', 'POST'),
173
+ overview: Copyleaks::ExportOverview.new('https://your-server.com/overview', 'POST')
174
+ )
175
+ copyleaks.export(auth_token, scan_id, 'export-1', model)
176
+ ```
177
+ For more details, refer to the Copyleaks Export Endpoint [Documentation](https://docs.copyleaks.com/reference/actions/downloads/export)
178
+ ##
179
+ ### Reading the AI alert from the completed webhook
180
+ When AI Text Detection is enabled for a scan (`aiGeneratedText.detect`) and AI text is found, the completed webhook carries a `suspected-ai-text` alert in `notifications.alerts`. Its `additionalData` is the AI detection result, encoded as a JSON string. The SDK decodes it for you.
181
+
182
+ ```ruby
183
+ require 'copyleaks'
184
+ require 'json'
185
+ require 'webrick'
186
+
187
+ # A WEBrick servlet, as in demo/webhookServer.rb. Mount it on your completed webhook URL:
188
+ # server.mount '/webhook/completed', CompletedWebhookServlet
189
+ class CompletedWebhookServlet < WEBrick::HTTPServlet::AbstractServlet
190
+ def do_POST(req, res)
191
+ payload = JSON.parse(req.body)
192
+ completed = Copyleaks::CompletedWebhook.new(**payload.transform_keys(&:to_sym))
193
+
194
+ alert = completed.ai_detection_alert # Copyleaks::Alerts, or nil when the scan produced no AI alert
195
+ if alert
196
+ begin
197
+ # nil when the alert has no data; raises JSON::ParserError when additionalData is not valid JSON
198
+ ai_result = alert.ai_detection_result
199
+ if ai_result && ai_result.summary
200
+ puts "AI: #{ai_result.summary.ai}, human: #{ai_result.summary.human}, model: #{ai_result.model_version}"
201
+ Array(ai_result.results).each do |result|
202
+ # classification: 1 = human, 2 = AI
203
+ Array(result.matches).each do |match|
204
+ puts "classification #{result.classification}: starts #{match.text.chars.starts.inspect}, lengths #{match.text.chars.lengths.inspect}"
205
+ end
206
+ end
207
+ end
208
+ rescue JSON::ParserError => e
209
+ warn "Could not decode the AI alert: #{e.message}"
210
+ end
211
+ end
212
+
213
+ # Acknowledge the webhook even when the AI alert could not be decoded.
214
+ res.status = 200
215
+ end
216
+ end
217
+ ```
218
+ - `ai_detection_alert` returns `nil` when the completed webhook contains no `suspected-ai-text` alert.
219
+ - `ai_detection_result` returns `nil` when the alert has no data or its data is not a JSON object, and raises `JSON::ParserError` when `additionalData` is not valid JSON. `completed.ai_detection_result` does the same in one call.
220
+ - The raw string is still available as `alert.additionalData`.
221
+
222
+ For more details on the alerts, refer to the Copyleaks scan alerts [Documentation](https://docs.copyleaks.com/reference/data-types/authenticity/scan-alerts)
223
+ ##
224
+ ### AI Text Detection
225
+ Use the AI detection client to determine if content was generated by artificial intelligence.
226
+
227
+ ```ruby
228
+ require 'copyleaks'
229
+ require 'base64'
230
+
231
+ # --- Your Credentials ---
232
+ USER_EMAIL = 'YOUR_EMAIL_ADDRESS'
233
+ USER_API_KEY = 'YOUR_API_KEY'
234
+ # --------------------
235
+
236
+ begin
237
+ scanId = DateTime.now.strftime('%Q').to_s
238
+ text = "Lions are social animals, living in groups called prides, typically consisting of several females, their offspring, and a few males. Female lions are the primary hunters, working together to catch prey. Lions are known for their strength, teamwork, and complex social structures."
239
+ submission = Copyleaks::NaturalLanguageSubmissionModel.new(
240
+ text,
241
+ nil, # language: nil detects it automatically
242
+ true, # sandbox
243
+ explain: true, # AI Logic: the response includes the patterns behind the result
244
+ sensitivity: 2 # 1 to 3
245
+ )
246
+
247
+ res = @copyleaks.ai_detection_client.submit_natural_language(_authToken, scanId, submission)
248
+ result = Copyleaks::CopyleaksAiTextDetectionResponseModel.from_json(res)
249
+ puts "AI: #{result.summary.ai}, human: #{result.summary.human}"
250
+
251
+ # Credits available for AI Text Detection
252
+ credits = @copyleaks.ai_detection_client.get_credits_balance(_authToken)['credits']
253
+
254
+ # File types accepted by AI Text Detection (no login needed)
255
+ file_types = @copyleaks.get_supported_ai_text_detection_file_types['supportedAiFileTypes']
256
+
257
+ end
258
+ ```
259
+ For a full guide please refer to our step by step [Guide](https://docs.copyleaks.com/guides/ai-detector/ai-text-detection/)
260
+
261
+ For a detailed understanding of the AI Text Detection process, refer to the Copyleaks detect natural language Endpoint [Documentation](https://docs.copyleaks.com/reference/actions/writer-detector/check/)
262
+ ##
263
+ ### Grammar Checker (WritingAssistantClient)
264
+ Get intelligent suggestions for improving grammar, spelling, style, and overall writing quality.
265
+
266
+ ```ruby
267
+ require 'copyleaks'
268
+ require 'base64'
269
+
270
+ # --- Your Credentials ---
271
+ USER_EMAIL = 'YOUR_EMAIL_ADDRESS'
272
+ USER_API_KEY = 'YOUR_API_KEY'
273
+ # --------------------
274
+
275
+ begin
276
+ text = "Lions are the only cat that live in groups, called pride. A prides typically consists of a few adult males, several feales, and their offspring. This social structure is essential for hunting and raising young cubs. Female lions, or lionesses are the primary hunters of the prid. They work together in cordinated groups to take down prey usually targeting large herbiores like zbras, wildebeest and buffalo. Their teamwork and strategy during hunts highlight the intelligence and coperation that are key to their survival."
277
+ scanId = DateTime.now.strftime('%Q').to_s
278
+ score_weights = Copyleaks::ScoreWeights.new(0.1, 0.2, 0.3, 0.4)
279
+ submission = Copyleaks::WritingAssistantSubmissionModel.new(
280
+ text,
281
+ )
282
+ submission.sandbox = true
283
+ submission.score = score_weights
284
+ res = @copyleaks.writing_assistant_client.submit_text(_authToken, scanId, submission)
285
+
286
+ end
287
+ ```
288
+ For a full guide please refer to our step by step [Guide](https://docs.copyleaks.com/guides/writing/check-grammar/)
289
+
290
+ For a detailed understanding of the Grammar Checker (WritingAssistantClient) process, refer to the Copyleaks writing feedback Endpoint [Documentation](https://docs.copyleaks.com/reference/actions/writing-assistant/check/)
291
+ ##
292
+ ### Text Moderation
293
+ Scan and moderate text content for unsafe, inappropriate, or policy-violating material across various categories.
294
+
295
+ ```ruby
296
+ require 'copyleaks'
297
+ require 'base64'
298
+
299
+ # --- Your Credentials ---
300
+ USER_EMAIL = 'YOUR_EMAIL_ADDRESS'
301
+ USER_API_KEY = 'YOUR_API_KEY'
302
+ # --------------------
303
+
304
+ begin
305
+ scanId = DateTime.now.strftime('%Q').to_s
306
+ labelsArray=[
307
+ Copyleaks::CopyleaksTextModerationLabel.new(Copyleaks::CopyleaksTextModerationConstants::ADULT_V1),
308
+ Copyleaks::CopyleaksTextModerationLabel.new(Copyleaks::CopyleaksTextModerationConstants::TOXIC_V1),
309
+ Copyleaks::CopyleaksTextModerationLabel.new(Copyleaks::CopyleaksTextModerationConstants::VIOLENT_V1),
310
+ Copyleaks::CopyleaksTextModerationLabel.new(Copyleaks::CopyleaksTextModerationConstants::PROFANITY_V1),
311
+ Copyleaks::CopyleaksTextModerationLabel.new(Copyleaks::CopyleaksTextModerationConstants::SELF_HARM_V1),
312
+ Copyleaks::CopyleaksTextModerationLabel.new(Copyleaks::CopyleaksTextModerationConstants::HARASSMENT_V1),
313
+ Copyleaks::CopyleaksTextModerationLabel.new(Copyleaks::CopyleaksTextModerationConstants::HATE_SPEECH_V1),
314
+ Copyleaks::CopyleaksTextModerationLabel.new(Copyleaks::CopyleaksTextModerationConstants::DRUGS_V1),
315
+ Copyleaks::CopyleaksTextModerationLabel.new(Copyleaks::CopyleaksTextModerationConstants::FIREARMS_V1),
316
+ Copyleaks::CopyleaksTextModerationLabel.new(Copyleaks::CopyleaksTextModerationConstants::CYBERSECURITY_V1)
317
+ ]
318
+
319
+ text_moderation_request = Copyleaks::CopyleaksTextModerationRequestModel.new(
320
+ text: "This is some text to scan.",
321
+ sandbox: true,
322
+ language: Copyleaks::CopyleaksTextModerationLanguages::ENGLISH,
323
+ labels: labelsArray
324
+ )
325
+ res = @copyleaks.text_moderation_client.submit_text(_authToken, scanId, text_moderation_request)
326
+
327
+ textModerationResponse = Copyleaks::CopyleaksTextModerationResponseModel.new(
328
+ moderations: res['moderations'],
329
+ legend: res['legend'],
330
+ scanned_document: res['scannedDocument'])
331
+
332
+ end
333
+ ```
334
+ For a full guide please refer to our step by step [Guide](https://docs.copyleaks.com/guides/moderation/moderate-text/)
335
+
336
+ For a detailed understanding of the Text moderation process, refer to the Copyleaks text moderation Endpoint [Documentation](https://docs.copyleaks.com/reference/actions/text-moderation/check/)
337
+ ##
338
+ ### AI Image Detection
339
+ Determine if a given image was generated or partially generated by an AI.
340
+
341
+ ```ruby
342
+ require 'copyleaks'
343
+ require 'base64'
344
+ # --- Your Credentials ---
345
+ USER_EMAIL = 'YOUR_EMAIL_ADDRESS'
346
+ USER_API_KEY = 'YOUR_API_KEY'
347
+ # --------------------
348
+ begin
349
+ puts "Submitting a new image for AI image detection..."
350
+
351
+ scanId = DateTime.now.strftime('%Q').to_s
352
+
353
+ # Read and encode your image file to base64 (read it in binary mode)
354
+ image_path = "Path/to/your/image.jpg" # Update this path to your image
355
+ base64_image = Base64.strict_encode64(File.binread(image_path))
356
+
357
+ model = Copyleaks::CopyleaksAiImageDetectionRequestModel.new(
358
+ base64_image,
359
+ "image.jpg",
360
+ Copyleaks::CopyleaksAiImageDetectionModels::AI_IMAGE_1_ULTRA,
361
+ true # sandbox mode
362
+ )
363
+
364
+ res = copyleaks.ai_image_detection_client.submit_(authToken, scanId, model)
365
+ rescue StandardError => e
366
+ puts "Error in test_image_detection: #{e.message}"
367
+ end
368
+ end
369
+ ```
370
+ For a full guide please refer to our step by step [Guide](https://docs.copyleaks.com/guides/ai-detector/ai-image-detection/)
371
+
372
+ For a detailed understanding of the AI Image Detection process, refer to the Copyleaks AI image detection Endpoint [Documentation](https://docs.copyleaks.com/reference/actions/ai-image-detector/check/)
373
+
374
+ To upload the raw image as multipart/form-data, which skips the base64 overhead, pass `nil` as the first argument and the bytes as `image:`. You can also pick the detection mask and locate objects:
375
+
376
+ ```ruby
377
+ model = Copyleaks::CopyleaksAiImageDetectionRequestModel.new(
378
+ nil, 'image.jpg', Copyleaks::CopyleaksAiImageDetectionModels::AI_IMAGE_1_ULTRA, true,
379
+ image: File.binread('Path/to/your/image.jpg'),
380
+ mask_type: Copyleaks::CopyleaksAiImageMaskTypes::HEATMAP, # BINARY (default), HEATMAP or NONE
381
+ object_detection: ['face', 'hand'] # up to 3 objects
382
+ )
383
+ res = copyleaks.ai_image_detection_client.check(authToken, scanId, model) # same as submit_
384
+ result = Copyleaks::CopyleaksAiImageDetectionResponseModel.from_json(res)
385
+ puts "AI detected: #{result.is_ai_detected}, objects: #{Array(result.detected_objects).map(&:object)}"
386
+ ```
387
+ `model.validate!` runs optional client-side checks (file name, extension and size) before you send the request.
388
+ ##
389
+ ### AI Image Detection (asynchronous)
390
+ Submit an image URL. The server answers right away and posts the result to your webhook. The webhook body has the same shape as the synchronous result, so `Copyleaks::CopyleaksAiImageDetectionResponseModel.from_json(JSON.parse(body))` reads it.
391
+
392
+ ```ruby
393
+ model = Copyleaks::CopyleaksAiImageDetectionAsyncRequestModel.new(
394
+ url: 'https://example.com/image.png',
395
+ file_name: 'image.png',
396
+ model: Copyleaks::CopyleaksAiImageDetectionModels::AI_IMAGE_1_ULTRA,
397
+ webhooks: Copyleaks::CopyleaksAsyncWebhooksModel.new('https://your-server.com/webhook/ai-image'),
398
+ mask_type: Copyleaks::CopyleaksAiImageMaskTypes::HEATMAP,
399
+ sandbox: true
400
+ )
401
+ copyleaks.ai_image_detection_client.submit_async(authToken, scanId, model)
402
+
403
+ # In your webhook handler:
404
+ result = Copyleaks::CopyleaksAiImageDetectionResponseModel.from_json(JSON.parse(request_body))
405
+ puts "Scan failed: #{result.error.code} #{result.error.message}" if result.error
406
+ ```
407
+ When the scan fails, the webhook body has an `error` (a `Copyleaks::Error` with `code`, `message`, and optionally `type`, `id`, `url` and `details`) instead of a result, so check `error` first. `developer_payload` returns the `developer_payload` you sent.
408
+
409
+ For more details, refer to the Copyleaks AI Image Detector Async Endpoint [Documentation](https://docs.copyleaks.com/reference/actions/ai-image-detector/submit)
410
+ ##
411
+ ### AI Video Detection
412
+ Submit a video URL. The server answers right away and posts the result to your webhook.
413
+
414
+ ```ruby
415
+ model = Copyleaks::CopyleaksAiVideoDetectionRequestModel.new(
416
+ url: 'https://example.com/video.mp4',
417
+ filename: 'video.mp4',
418
+ model: Copyleaks::CopyleaksAiVideoDetectionModels::AI_VIDEO_1_PRO,
419
+ webhooks: Copyleaks::CopyleaksAsyncWebhooksModel.new('https://your-server.com/webhook/ai-video'),
420
+ sandbox: true
421
+ )
422
+ copyleaks.ai_video_detection_client.submit(authToken, scanId, model)
423
+
424
+ # In your webhook handler:
425
+ result = Copyleaks::CopyleaksAiVideoDetectionResponseModel.from_json(JSON.parse(request_body))
426
+ if result.error
427
+ puts "Scan failed: #{result.error.code} #{result.error.message}"
428
+ else
429
+ puts "AI detected: #{result.is_ai_detected}, overall ratio: #{result.summary.overall_ai_ratio}"
430
+ end
431
+ ```
432
+ When the scan fails, the webhook body has an `error` (a `Copyleaks::Error`) instead of a result, so check `error` first. `developer_payload` returns the `developer_payload` you sent.
433
+
434
+ For more details, refer to the Copyleaks AI Video Detection Endpoint [Documentation](https://docs.copyleaks.com/reference/actions/ai-video-detector/submit)
435
+ ##
436
+ ### Image Plagiarism Detection
437
+ Search the web for copies of an image. The image is uploaded as multipart/form-data and the matches are in the response.
438
+
439
+ ```ruby
440
+ model = Copyleaks::CopyleaksImagePlagiarismRequestModel.new(
441
+ image: File.binread('Path/to/your/photo.jpg'),
442
+ filename: 'photo.jpg',
443
+ sandbox: true
444
+ )
445
+ res = copyleaks.image_plagiarism_client.check(authToken, scanId, model)
446
+ result = Copyleaks::CopyleaksImagePlagiarismResponseModel.from_json(res)
447
+ puts "Matches: #{result.matches.score.total_matches}"
448
+ result.matches.internet.each { |match| puts "#{match.url} (#{match.match_type == 0 ? 'full' : 'partial'})" }
449
+ ```
450
+ For more details, refer to the Copyleaks Image Plagiarism Detection Endpoint [Documentation](https://docs.copyleaks.com/reference/actions/image-plagiarism-detector/check)
451
+ ##
452
+ ### Account and lookups
453
+
454
+ ```ruby
455
+ copyleaks.get_credits_balance(authToken) # plagiarism credits
456
+ copyleaks.ai_detection_client.get_credits_balance(authToken) # AI Text Detection credits
457
+ copyleaks.get_repository_info(authToken, 'my-repo-id') # Private Cloud Hub repository (Admin role)
458
+
459
+ # Usage history as CSV. With a block, the CSV is streamed in chunks.
460
+ File.open('usage.csv', 'w') do |file|
461
+ copyleaks.get_usages_history_csv(authToken, '01-09-2026', '30-09-2026') { |chunk| file.write(chunk) }
462
+ end
463
+
464
+ # Public lookups, no login needed
465
+ copyleaks.get_supported_file_types
466
+ copyleaks.get_supported_ai_text_detection_file_types
467
+ copyleaks.get_allowed_cross_languages
468
+ copyleaks.get_ocr_supported_languages
469
+ ```
470
+
471
+ ##
472
+ ### Further Resources
473
+
474
+ * **Copyleaks API Dashboard:** Manage your API keys, monitor usage, and view analytics from your personalized dashboard. [Access Dashboard](https://api.copyleaks.com/dashboard)
475
+ * **Copyleaks SDK Documentation:** Explore comprehensive guides, API references, and code examples for seamless integration. [Read Documentation](https://docs.copyleaks.com/resources/sdks/overview/)
476
+
477
+
478
+ ## Development
479
+ The offline test suite runs against a local stub server and never calls the Copyleaks API:
480
+
481
+ ```bash
482
+ rake test
483
+ ```
484
+
485
+ ## Support
486
+ * If you need assistance, please contact Copyleaks Support via our support portal: Contact Copyleaks [Support](https://help.copyleaks.com/s/contactsupport).
487
+ * To arrange a product demonstration, book a demo here: [Booking Link](https://copyleaks.com/book-a-demo).