rswag-ui 2.16.0 → 3.0.0.pre

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 (30) hide show
  1. checksums.yaml +4 -4
  2. data/Rakefile +2 -4
  3. data/lib/generators/rswag/ui/custom/custom_generator.rb +3 -1
  4. data/lib/generators/rswag/ui/install/install_generator.rb +3 -2
  5. data/lib/generators/rswag/ui/install/templates/rswag_ui.rb +3 -2
  6. data/lib/rswag/ui/configuration.rb +6 -12
  7. data/lib/rswag/ui/engine.rb +3 -1
  8. data/lib/rswag/ui/index.erb +0 -1
  9. data/lib/rswag/ui/middleware.rb +9 -7
  10. data/lib/rswag/ui.rb +2 -4
  11. data/lib/tasks/rswag-ui_tasks.rake +3 -2
  12. data/node_modules/@scarf/scarf/LICENSE +201 -0
  13. data/node_modules/@scarf/scarf/README.md +198 -0
  14. data/node_modules/@scarf/scarf/package.json +36 -0
  15. data/node_modules/@scarf/scarf/report.js +574 -0
  16. data/node_modules/swagger-ui-dist/README.md +18 -0
  17. data/node_modules/swagger-ui-dist/package.json +4 -2
  18. data/node_modules/swagger-ui-dist/swagger-ui-bundle.js +1 -2
  19. data/node_modules/swagger-ui-dist/swagger-ui-bundle.js.map +1 -1
  20. data/node_modules/swagger-ui-dist/swagger-ui-es-bundle-core.js +1 -1
  21. data/node_modules/swagger-ui-dist/swagger-ui-es-bundle-core.js.map +1 -1
  22. data/node_modules/swagger-ui-dist/swagger-ui-es-bundle.js +1 -2
  23. data/node_modules/swagger-ui-dist/swagger-ui-es-bundle.js.map +1 -1
  24. data/node_modules/swagger-ui-dist/swagger-ui-standalone-preset.js +1 -2
  25. data/node_modules/swagger-ui-dist/swagger-ui-standalone-preset.js.map +1 -1
  26. data/node_modules/swagger-ui-dist/swagger-ui.css +1 -1
  27. data/node_modules/swagger-ui-dist/swagger-ui.css.map +1 -1
  28. data/node_modules/swagger-ui-dist/swagger-ui.js +1 -1
  29. data/node_modules/swagger-ui-dist/swagger-ui.js.map +1 -1
  30. metadata +13 -8
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 0111df3cb0d048acb6daffa69c09c900e9d45b3a792ce8656c27534ac05862e6
4
- data.tar.gz: 66a157cc07cc2e01d7e790061c6842af5a540458886155808111eb111569087e
3
+ metadata.gz: 64d094a1388a849e9419bc189b4d6f724970c953f0aba618e83b464912d5ac41
4
+ data.tar.gz: '080391f920628eca9287d3f78ce516b1899b4105c97907b090a3f6903933225b'
5
5
  SHA512:
6
- metadata.gz: 58b9497027fc293e255074e469333600a09ce0b5b394874d5b34c0ef89ac25c8a4225f9424a4aca18663850d882f374eed154cdb6081d11d8898df2822581b79
7
- data.tar.gz: 5d8b838c528924accbfa7fdf2aef94abcac5fcf8d6cbaa4005203352645af2ceae3695f2f38fe822cef249242e9d802240063e37fd8eea29eefbb17518481045
6
+ metadata.gz: 765ef6064752487a8f92d8ce9778163bdc725fc72c3d5566a1fb10b05aae75936b50d08524570781918a6e184ab6409629cfb09f8f6d31850377d3d51703600e
7
+ data.tar.gz: f08d5adc53efbcdbfb0afcd0fbb515cd6d291b8d119ff4e06c8ff36c97402d486d2c11b7ca800b2f75b29dab678aa28ab8e3bdecdccc7d067d08348db67d0a85
data/Rakefile CHANGED
@@ -1,4 +1,6 @@
1
1
  #!/usr/bin/env rake
2
+ # frozen_string_literal: true
3
+
2
4
  begin
3
5
  require 'bundler/setup'
4
6
  rescue LoadError
@@ -20,8 +22,4 @@ RDoc::Task.new(:rdoc) do |rdoc|
20
22
  rdoc.rdoc_files.include('lib/**/*.rb')
21
23
  end
22
24
 
23
-
24
-
25
-
26
25
  Bundler::GemHelper.install_tasks
27
-
@@ -1,9 +1,11 @@
1
+ # frozen_string_literal: true
2
+
1
3
  require 'rails/generators'
2
4
 
3
5
  module Rswag
4
6
  module Ui
5
7
  class CustomGenerator < Rails::Generators::Base
6
- source_root File.expand_path('../../../../../../lib/rswag/ui', __FILE__)
8
+ source_root File.expand_path('../../../../../lib/rswag/ui', __dir__)
7
9
 
8
10
  def add_custom_index
9
11
  copy_file('index.erb', 'app/views/rswag/ui/home/index.html.erb')
@@ -1,10 +1,11 @@
1
+ # frozen_string_literal: true
2
+
1
3
  require 'rails/generators'
2
4
 
3
5
  module Rswag
4
6
  module Ui
5
-
6
7
  class InstallGenerator < Rails::Generators::Base
7
- source_root File.expand_path('../templates', __FILE__)
8
+ source_root File.expand_path('templates', __dir__)
8
9
 
9
10
  def add_initializer
10
11
  template('rswag_ui.rb', 'config/initializers/rswag_ui.rb')
@@ -1,5 +1,6 @@
1
- Rswag::Ui.configure do |c|
1
+ # frozen_string_literal: true
2
2
 
3
+ Rswag::Ui.configure do |c|
3
4
  # List the Swagger endpoints that you want to be documented through the
4
5
  # swagger-ui. The first parameter is the path (absolute or relative to the UI
5
6
  # host) to the corresponding endpoint and the second is a title that will be
@@ -8,7 +9,7 @@ Rswag::Ui.configure do |c|
8
9
  # (under openapi_root) as JSON or YAML endpoints, then the list below should
9
10
  # correspond to the relative paths for those endpoints.
10
11
 
11
- c.swagger_endpoint '/api-docs/v1/swagger.yaml', 'API V1 Docs'
12
+ c.openapi_endpoint '/api-docs/v1/openapi.yaml', 'API V1 Docs'
12
13
 
13
14
  # Add Basic Auth in case your API is private
14
15
  # c.basic_auth_enabled = true
@@ -1,14 +1,13 @@
1
+ # frozen_string_literal: true
2
+
1
3
  require 'ostruct'
2
4
  require 'rack'
3
5
 
4
6
  module Rswag
5
7
  module Ui
6
8
  class Configuration
7
- attr_reader :template_locations
8
- attr_accessor :basic_auth_enabled
9
- attr_accessor :config_object
10
- attr_accessor :oauth_config_object
11
- attr_reader :assets_root
9
+ attr_reader :template_locations, :assets_root
10
+ attr_accessor :basic_auth_enabled, :config_object, :oauth_config_object
12
11
 
13
12
  def initialize
14
13
  @template_locations = [
@@ -17,19 +16,14 @@ module Rswag
17
16
  # backwards compatible override location
18
17
  "#{Rack::Directory.new('').root}/app/views/rswag/ui/home/index.html.erb",
19
18
  # default location
20
- File.expand_path('../index.erb', __FILE__)
19
+ File.expand_path('index.erb', __dir__)
21
20
  ]
22
- @assets_root = File.expand_path('../../../../node_modules/swagger-ui-dist', __FILE__)
21
+ @assets_root = File.expand_path('../../../node_modules/swagger-ui-dist', __dir__)
23
22
  @config_object = {}
24
23
  @oauth_config_object = {}
25
24
  @basic_auth_enabled = false
26
25
  end
27
26
 
28
- def swagger_endpoint(url, name)
29
- Rswag::Ui.deprecator.warn('Rswag::Ui: WARNING: The method will be renamed to "openapi_endpoint" in v3.0')
30
- openapi_endpoint(url, name)
31
- end
32
-
33
27
  def openapi_endpoint(url, name)
34
28
  @config_object[:urls] ||= []
35
29
  @config_object[:urls] << { url: url, name: name }
@@ -1,3 +1,5 @@
1
+ # frozen_string_literal: true
2
+
1
3
  require 'rswag/ui/middleware'
2
4
  require 'rswag/ui/basic_auth'
3
5
 
@@ -18,7 +20,7 @@ module Rswag
18
20
  end
19
21
 
20
22
  rake_tasks do
21
- load File.expand_path('../../../tasks/rswag-ui_tasks.rake', __FILE__)
23
+ load File.expand_path('../../tasks/rswag-ui_tasks.rake', __dir__)
22
24
  end
23
25
  end
24
26
  end
@@ -4,7 +4,6 @@
4
4
  <head>
5
5
  <meta charset="UTF-8">
6
6
  <title>Swagger UI</title>
7
- <link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
8
7
  <link rel="stylesheet" type="text/css" href="./swagger-ui.css" >
9
8
  <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
10
9
  <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
@@ -1,20 +1,22 @@
1
+ # frozen_string_literal: true
2
+
1
3
  module Rswag
2
4
  module Ui
3
5
  class Middleware < Rack::Static
4
-
5
6
  def initialize(app, config)
6
7
  @config = config
7
- super(app, urls: [ '' ], root: config.assets_root )
8
+ super(app, urls: [''], root: config.assets_root)
8
9
  end
9
10
 
10
11
  def call(env)
11
12
  if base_path?(env)
12
- redirect_uri = env['SCRIPT_NAME'].chomp('/') + '/index.html'
13
- return [ 301, { 'Location' => redirect_uri }, [ ] ]
13
+ redirect_uri = "#{env['SCRIPT_NAME'].chomp('/')}/index.html"
14
+ return [301, { 'Location' => redirect_uri }, []]
14
15
  end
15
16
 
16
17
  if index_path?(env)
17
- return [ 200, { 'Content-Type' => 'text/html', 'Content-Security-Policy' => csp }, [ render_template ] ]
18
+ return [200, { 'Content-Type' => 'text/html', 'Content-Security-Policy' => csp },
19
+ [render_template]]
18
20
  end
19
21
 
20
22
  super
@@ -23,11 +25,11 @@ module Rswag
23
25
  private
24
26
 
25
27
  def base_path?(env)
26
- env['REQUEST_METHOD'] == "GET" && env['PATH_INFO'] == "/"
28
+ env['REQUEST_METHOD'] == 'GET' && env['PATH_INFO'] == '/'
27
29
  end
28
30
 
29
31
  def index_path?(env)
30
- env['REQUEST_METHOD'] == "GET" && env['PATH_INFO'] == "/index.html"
32
+ env['REQUEST_METHOD'] == 'GET' && env['PATH_INFO'] == '/index.html'
31
33
  end
32
34
 
33
35
  def render_template
data/lib/rswag/ui.rb CHANGED
@@ -1,3 +1,5 @@
1
+ # frozen_string_literal: true
2
+
1
3
  require 'rswag/ui/configuration'
2
4
  require 'rswag/ui/engine'
3
5
 
@@ -10,9 +12,5 @@ module Rswag
10
12
  def self.config
11
13
  @config ||= Configuration.new
12
14
  end
13
-
14
- def self.deprecator
15
- @deprecator ||= ActiveSupport::Deprecation.new('3.0', 'rswag-ui')
16
- end
17
15
  end
18
16
  end
@@ -1,8 +1,9 @@
1
+ # frozen_string_literal: true
2
+
1
3
  namespace :rswag do
2
4
  namespace :ui do
3
-
4
5
  desc 'TODO'
5
- task :copy_assets, [ :dest ] do |t, args|
6
+ task :copy_assets, [:dest] do |_t, args|
6
7
  dest = args[:dest]
7
8
  FileUtils.rm_r(dest, force: true)
8
9
  FileUtils.mkdir_p(dest)
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright 2020 Scarf Systems, Inc.
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
@@ -0,0 +1,198 @@
1
+ # scarf-js
2
+
3
+ ![](https://github.com/scarf-sh/scarf-js/workflows/CI/badge.svg)
4
+ [![npm version](https://badge.fury.io/js/%40scarf%2Fscarf.svg)](https://badge.fury.io/js/%40scarf%2Fscarf)
5
+ <a href="https://www.npmjs.com/package/@scarf/scarf">![](https://img.shields.io/npm/dw/@scarf/scarf)</a>
6
+ <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=fc72d03c-c3a2-4736-b243-10eeff839778" />
7
+ <a href="https://tinyurl.com/scarf-community-slack"><img src="https://img.shields.io/badge/Scarf%20Community%20-Slack-blue" alt="Join the Scarf Community Slack" />
8
+ </a>
9
+
10
+ Scarf is like Google Analytics for your npm packages. By sending some basic
11
+ details after installation, this package can help you can gain insight into how
12
+ your packages are used and by which companies. Scarf aims to help open-source developers
13
+ fund their work when it is used commercially.
14
+
15
+ To read more about why we wrote this library, check out [this post](https://github.com/scarf-sh/scarf-js/blob/master/WHY.org) on the topic.
16
+
17
+ ### Features
18
+
19
+ - No dependencies.
20
+ - Fully transparent to the user. Scarf will log its behavior to the console
21
+ during installation. It will never silently report analytics for someone that
22
+ hasn't explictly given permission to do so.
23
+ - Never interrupts your package installation. Reporting is done on a best effort basis.
24
+
25
+ ### Installing
26
+
27
+ You'll first need to create a library entry on [Scarf](https://scarf.sh). Once
28
+ created, add a dependency on this library to your own:
29
+
30
+ ```bash
31
+ npm i --save @scarf/scarf
32
+ ```
33
+
34
+ Once your library is published to npm with this change, Scarf will automatically
35
+ collect stats on install, no additional code is required!
36
+
37
+ Head to your package's dashboard on Scarf to see your reports when available.
38
+
39
+ ### Configuring
40
+
41
+ Users of your package will be opted in by default and can opt out by setting the
42
+ `SCARF_ANALYTICS=false` environment variable. If you'd like Scarf analytics to
43
+ instead be opt-in, you can set this by adding an entry to your `package.json`
44
+
45
+
46
+ ```json5
47
+ // your-package/package.json
48
+
49
+ {
50
+ // ...
51
+ "scarfSettings": {
52
+ "defaultOptIn": false
53
+ }
54
+ // ...
55
+ }
56
+ ```
57
+
58
+ Scarf will now be opt-out by default, and users can set `SCARF_ANALYTICS=true`
59
+ to opt in.
60
+
61
+ Regardless of the default state, Scarf will log what it is doing to users who
62
+ haven't explictly opted in or out.
63
+
64
+ By default, scarf-js will only trigger analytics when your package is installed as a dependency of another package, or is being installed globally. This ensures that scarf-js analytics will not be triggered on `npm install` being run _within your project_. To change this, you can add:
65
+
66
+ ```json5
67
+ // your-package/package.json
68
+
69
+ {
70
+ // ...
71
+ "scarfSettings": {
72
+ "allowTopLevel": true
73
+ }
74
+ // ...
75
+ }
76
+ ```
77
+
78
+
79
+ #### Full Configuration Example
80
+
81
+ ```json5
82
+ // your-package/package.json
83
+
84
+ {
85
+ // ...
86
+ "scarfSettings": {
87
+ // Toggles whether Scarf is enabled for this package
88
+ "enabled": true,
89
+ // Enables Scarf when users run npm install directly in your repository
90
+ // Scarf will try to report the Git commit SHA of your repository if it can
91
+ // be obtained.
92
+ "allowTopLevel": true,
93
+ // Users will be opted into analytics by default
94
+ "defaultOptIn": true,
95
+ // By default, Scarf searches for its own location in your build's dependency
96
+ // graph to ensure reporting can be done for all packages using Scarf.
97
+ // For large projects with lots of dependencies, generating that dependency
98
+ // graph takes more time than Scarf allots for its entire process, so Scarf
99
+ // will always time out. `skipTraversal` is an optional flag for large
100
+ // applications to skip that traversal entirely. Use this flag with caution and
101
+ // care, as it will break Scarf analytics for all other packages you depend
102
+ // on in your build.
103
+ "skipTraversal": false
104
+ }
105
+ // ...
106
+ }
107
+ ```
108
+
109
+ ### FAQ
110
+
111
+ #### What information does scarf-js provide me as a package author?
112
+
113
+ - Understanding your user-base
114
+ - Which companies are using your package?
115
+ - Is your project growing or shrinking? Where? On which platforms?
116
+ - Which versions of your package are being used?
117
+
118
+ #### As a user of a package using scarf-js, what information does scarf-js send about me?
119
+
120
+ *Scarf does not store personally identifying information.* Scarf aims to collect information that is helpful for:
121
+ - Open Source package maintainence
122
+ - Open Source commercialization
123
+
124
+ Specifically, scarf-js sends:
125
+
126
+ - The operating system you are using
127
+ - Your IP address will be used to look up any available company information. _Scarf does not store the actual IP address_
128
+ - Limited dependency tree information. Scarf sends the name and version of the package(s) that directly depend on scarf-js. Additionally, scarf-js will send SHA256-hashed name and version for the following packages in the dependency tree:
129
+ - Packages that depend on a package that depends on scarf-js.
130
+ - The root package of the dependency tree.
131
+ This allows Scarf to provide information for maintainers about which public packages are using their own, without exposing identifying details of non-public packages.
132
+
133
+ You can have scarf-js print the exact JSON payload it sends by setting `SCARF_VERBOSE=true` in your environment.
134
+
135
+ #### As a user of a package using scarf-js, how can I opt out of analytics?
136
+
137
+ Scarf's analytics help support developers of the open source packages you are
138
+ using, so enabling analytics is appreciated. However, if you'd like to opt out,
139
+ you can add your preference to your project's `package.json`:
140
+
141
+
142
+ ```json5
143
+ // your-package/package.json
144
+
145
+ {
146
+ // ...
147
+ "scarfSettings": {
148
+ "enabled": false
149
+ }
150
+ // ...
151
+ }
152
+ ```
153
+
154
+ Alternatively, you can set this variable in your environment:
155
+
156
+ ```shell
157
+ export SCARF_ANALYTICS=false
158
+ ```
159
+
160
+ You can also set this variable in accordance to the [Console Do Not Track](https://consoledonottrack.com/) standard:
161
+ ```shell
162
+ export DO_NOT_TRACK=1
163
+ ```
164
+
165
+ Either route will disable Scarf for all packages.
166
+
167
+ #### I distribute a package on npm, and scarf-js is in our dependency tree. Can I disable the analytics for my downstream dependents?
168
+
169
+ Yes. By opting out of analytics via `package.json`, any package upstream will have analytics disbabled.
170
+
171
+ ```json5
172
+ // your-package/package.json
173
+
174
+ {
175
+ // ...
176
+ "scarfSettings": {
177
+ "enabled": false
178
+ }
179
+ // ...
180
+ }
181
+ ```
182
+
183
+ Installers of your packages will have scarf-js disabled for all dependencies upstream from yours.
184
+
185
+
186
+ ### Developing
187
+
188
+ Setting the environment variable `SCARF_LOCAL_PORT=8080` will configure Scarf to
189
+ use http://localhost:8080 as the analytics endpoint host.
190
+
191
+ ### Future work
192
+
193
+ Future releases of scarf-js will provide a module of utility functions to
194
+ collect usage analytics in addition to the current installation analytics.
195
+
196
+ ### Community
197
+
198
+ Join the [Scarf-Community workspace](https://tinyurl.com/scarf-community-slack) on Slack and find us in the #scarf-js channel. We'll keep an eye out for your questions and concerns.
@@ -0,0 +1,36 @@
1
+ {
2
+ "name": "@scarf/scarf",
3
+ "version": "1.4.0",
4
+ "description": "Scarf is like Google Analytics for your npm packages. Gain insights into how your packages are installed and used, and by which companies.",
5
+ "main": "report.js",
6
+ "homepage": "https://github.com/scarf-sh/scarf-js",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/scarf-sh/scarf-js.git"
10
+ },
11
+ "files": [
12
+ "report.js"
13
+ ],
14
+ "scripts": {
15
+ "postinstall": "node ./report.js",
16
+ "test": "jest --verbose"
17
+ },
18
+ "author": "Scarf Systems",
19
+ "license": "Apache-2.0",
20
+ "devDependencies": {
21
+ "jest": "^25.3.0",
22
+ "minimist": "^1.2.2",
23
+ "standard": "^14.3.1"
24
+ },
25
+ "standard": {
26
+ "globals": [
27
+ "expect",
28
+ "test",
29
+ "jest",
30
+ "beforeAll",
31
+ "afterAll",
32
+ "fail",
33
+ "describe"
34
+ ]
35
+ }
36
+ }